Control API - utilizadores e apps autenticadoras

Utilize a FoxIDs Control API para provisionar utilizadores internos e gerir as apps autenticadoras registadas por cada utilizador. Este guia centra-se nas operações que permitem sincronizar registos entre deployments FoxIDs.

Antes de chamar estas operações, configure a autenticação e os direitos de acesso da Control API. O Swagger continua a ser a referência exata para todas as propriedades de utilizador, filtros, regras de validação e esquemas de response:

• Swagger (OpenAPI) JSON
• Swagger UI

Base dos endpoints

Os exemplos utilizam o FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Substitua {tenant_name} pelo nome do tenant e {track_name} pelo nome técnico do ambiente. Altere o host para um deployment self-hosted. Envie o access token da Control API no header Authorization: Bearer {access_token}.

As operações de utilizadores e apps autenticadoras exigem um direito de utilizador para o ambiente de destino. Conceda apenas a operação read, create, update ou delete necessária através da hierarquia de direitos da Control API.

Identificadores de utilizador

Cada utilizador interno tem de possuir pelo menos um identificador de início de sessão: e-mail, telefone ou nome de utilizador. E-mails e nomes de utilizador são normalizados para minúsculas e os espaços iniciais e finais são removidos.

As operações individuais identificam o utilizador com o query parameter email, phone ou username. A response também contém um userId gerado pelo servidor. Este ID é único e persistente, mesmo quando um identificador muda, e deve ser usado para associar apps autenticadoras ou outros recursos.

Operações de utilizador

As operações individuais estão agrupadas em tenant users no Swagger.

Use phone={phone} ou username={username} em vez de email={email} quando adequado. Acrescente cada endpoint à base dos endpoints.

Listar e filtrar utilizadores

GET /!users aceita filterEmail, filterPhone, filterUsername, filterUserId e filterClaimValue. Cada filtro procura correspondências parciais sem diferenciar maiúsculas de minúsculas. Com vários filtros, o utilizador é devolvido se qualquer um corresponder.

A response contém uma collection data e um paginationToken opaco. Repita o mesmo request com o valor devolvido como paginationToken para obter a página seguinte. Continue até deixar de existir token. Não o interprete nem altere.

A response indica se existe uma password e quando foi alterada, mas nunca devolve a password ou o seu hash atual.

Criar um utilizador

O create-request suporta estado da conta, identificadores verificados, claims personalizados, política de password, configuração por e-mail ou SMS e definições MFA por utilizador. Este exemplo cria um utilizador sem password e exige a sua configuração por e-mail:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [{ "claim": "role", "values": ["employee"] }]
}

Um create-request pode conter password em texto simples, campos de hash suportados ou nenhuma credencial. Nunca envie ambos os formatos. Passwords em texto simples são validadas pela política; hashes importados não. Sem credenciais, use setPasswordEmail ou setPasswordSms se o utilizador tiver de criar uma password ao iniciar sessão.

Criar um utilizador existente devolve 409 Conflict, e aplica-se o limite de utilizadores do plano do tenant. Uma operação de utilizador simultânea pode bloquear temporariamente a criação; repita 423 Locked após um curto intervalo.

Atualizar um utilizador

PUT /!user é uma atualização completa, não um patch. Leia o utilizador atual, preserve propriedades inalteradas, aplique as alterações e envie toda a representação editável. A collection de claims e os flags de conta/MFA são substituídos. Passwords e registos de apps têm operações próprias.

Identifique o utilizador com email, phone ou username. Para alterar um identificador, mantenha o valor atual e defina updateEmail, updatePhone ou updateUsername. Uma string vazia remove-o; omitir a propriedade mantém-no. Preserve pelo menos um identificador de início de sessão.

Alterar disableAccount de false para true revoga refresh token grants e sessões ativas. Reativar permite novos inícios de sessão, mas não restaura sessões revogadas.

Gerir passwords

Use PUT /!usersetpassword para administração ou migração:

• Forneça password para aplicar a política e atualizar o histórico.
• Forneça passwordHashAlgorithm, passwordHash e passwordHashSalt para importar um hash suportado sem validação da política.
• Omita ambos os formatos para remover a password atual.

passwordLastChanged é tempo Unix opcional em segundos. changePassword exige uma nova password no próximo início de sessão aplicável. Use PUT /!userchangepassword quando conhece a atual; esta é verificada e a nova é validada segundo a política e o histórico.

O endpoint de histórico destina-se a migração e recuperação controladas. O detalhe contém material de hash e PUT substitui todo o histórico. Proteja-o como hashes importados e não registe request/response bodies.

Provisionamento em massa

PUT /!users aceita entre 1 e 1.000 utilizadores por request. No máximo 100 entries podem incluir passwords em texto simples. Requests sem elas, incluindo hashes pré-calculados suportados, podem incluir 1.000 utilizadores.

O carregamento em massa cria ou substitui utilizadores; não combina propriedades nem pode mudar o nome dos identificadores. Trate-o como importação de substituição. Use a atualização individual para preservar o estado e o userId persistente.

DELETE /!users aceita entre 1 e 1.000 e-mails, telefones ou nomes de utilizador em userIdentifiers. Consulte Carregar muitos utilizadores para formatos, desempenho e seed tool.

Eliminar utilizadores e revogar acesso

A eliminação individual ou em massa revoga refresh token grants e sessões ativas antes de eliminar a conta. É permanente. Use as operações delete das apps autenticadoras para remover apenas os seus registos.

Os requests de criação, atualização, password e eliminação são incluídos no audit log do Control. As leituras não são escritas como audit-events.

Registos de apps autenticadoras

As operações de apps autenticadoras estão agrupadas em tenant user authenticator apps no Swagger. Uma operação de lista devolve resumos seguros, enquanto a operação de detalhe devolve os dados sensíveis necessários para uma sincronização controlada.

Adicione cada endpoint à base dos endpoints. Exemplo:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Recurso de registo

A criação e a atualização utilizam o recurso de registo completo:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

As propriedades têm o seguinte comportamento:

• userId é o ID de utilizador FoxIDs estável.
• id é um ID de registo persistente fornecido pelo cliente durante a criação. Seleciona o registo durante a atualização e não pode ser alterado.
• createTime é expresso em segundos Unix. É opcional durante a criação e, por predefinição, utiliza a hora atual. Se for omitido durante uma atualização, o valor existente é preservado.
• secret é o TOTP secret partilhado e é obrigatório durante a criação e atualização.
• recoveryCode contém os dados de hash do recovery code e é omitido quando não existe um recovery code configurado.

Um utilizador pode ter no máximo cinco registos de apps autenticadoras. A criação com um ID existente devolve 409 Conflict; a criação após atingir o limite devolve 400 Bad Request.

Sincronizar registos

Um serviço de sincronização pode combinar a Authenticator App notification API interativa com estas operações da Control API:

1. Receba a notification registered que contém user_id e registration_id.
2. Obtenha o registo do source deployment através da operação de detalhe.
3. Crie o registo no target deployment ou atualize-o se já existir o mesmo ID.

As operações da Control API para criar, atualizar e eliminar não chamam a Authenticator App notification API. A sincronização não cria, portanto, um ciclo de notification.

Segurança

As operações de detalhe, criação e atualização expõem ou aceitam um secret de app autenticadora e dados de hash do recovery code. Conceda o direito de utilizador necessário apenas a clientes de confiança, utilize TLS, proteja os payloads armazenados e não registe request ou response bodies.

Utilize a operação de lista quando apenas forem necessários IDs de registo e datas de criação. Não devolve o secret nem dados de hash do recovery code.

Propriedade de compatibilidade

A propriedade activeTwoFactorApp da API geral de utilizador está deprecated e a remoção está prevista após 1 de agosto de 2027. Numa update-request, false continua a eliminar todos os registos por compatibilidade; true ou um valor omitido deixa-os inalterados. As novas integrações devem utilizar os endpoints de apps autenticadoras.

Responses de erro

As responses de erro comuns das operações de utilizadores e apps autenticadoras são:

• 400 Bad Request se identificadores, credenciais, filtros ou dados forem inválidos, ou se o limite de registos for atingido.
• 401 Unauthorized se o access token estiver ausente ou inválido.
• 403 Forbidden se o cliente não tiver o direito de utilizador necessário para o ambiente.
• 404 Not Found se o utilizador ou registo da app não existir.
• 409 Conflict se o utilizador já existir ou um ID de registo for reutilizado.
• 423 Locked se a criação ou importação em massa estiver temporariamente bloqueada. Repita após um curto intervalo.

Utilize o response body para detalhes de validação. Consulte o Swagger UI para as responses declaradas por operação.

Documentação relacionada

• Autenticação e direitos de acesso da Control API
• Visão geral do FoxIDs Control
• Utilizadores internos
• Autenticação de dois fatores e multifator
• Carregar muitos utilizadores