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. Os endereços de e-mail podem ter até 100 carateres e os nomes de utilizador até 60 carateres. Os endereços de e-mail e os nomes de utilizador são normalizados para minúsculas e os espaços em branco circundantes são removidos de todos os identificadores.

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.

Para utilizadores de Directory Connector, preserve a ligação estável directoryUserId ao atualizar a conta. A sincronização a pedido substitui identificadores, definições e claims geridos pelo diretório; altere esses valores no diretório autoritativo. Registos de aplicações de autenticação e atribuições de acesso FoxIDs são mantidos.

Operações de utilizador

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

Os claims personalizados podem incluir um valueType opcional: String, Boolean, Number, JsonObject ou JsonArray. Todas as entradas em values permanecem cadeias de caracteres e partilham o tipo selecionado. Omita valueType para String. A API rejeita valores que não correspondam ao tipo selecionado; preserve-o ao ler e atualizar claims. As mesmas opções aplicam-se aos claims dos nós das estruturas de acesso e aos claims do administrador inicial ao criar um tenant. Consulte tipos de valores dos claims para conhecer os limites numéricos e o comportamento JWT/SAML.

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.

Os claims personalizados dos utilizadores não podem utilizar nomes de claims protegidos, como sid e auth_time.

Gerir passwords

Use PUT /!usersetpassword para uma definição administrativa ou migração. Suporta três modos:

• Forneça password para aplicar a política selecionada e atualizar o histórico.
• Forneça passwordHashAlgorithm e passwordHash, mais passwordHashSalt quando exigido pelo algoritmo, para importar um hash pré-calculado suportado sem validar a política.
• Omita ambos os formatos para remover a palavra-passe atual do utilizador.

Os mesmos formatos de hash são aceites na criação de um utilizador ou no aprovisionamento em massa:

Por exemplo, este pedido administrativo de palavra-passe importa um hash bcrypt sintético:

{
  "email": "alice@example.com",
  "passwordHashAlgorithm": "bcrypt",
  "passwordHash": "$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC"
}

Não inclua password com campos de hash. Um hash ou salt sem algoritmo é rejeitado. Cadeias bcrypt malformadas, variantes não suportadas, custos fora do intervalo e salts bcrypt separados são rejeitados antes da persistência. Consulte o hashing de palavras-passe para os parâmetros e o limite bcrypt de 72 bytes.

O valor opcional passwordLastChanged é o tempo Unix em segundos. Use changePassword para exigir uma nova palavra-passe no próximo início de sessão aplicável. Importar um hash ignora as verificações da política durante a importação; a política selecionada continua a aplicar-se ao iniciar sessão. O início de sessão preserva o hash importado e a data de alteração. Definir ou alterar uma palavra-passe em texto simples usa o formato PBKDF2 predefinido.

Use PUT /!userchangepassword quando a palavra-passe atual é conhecida. Verifica-a e valida a nova face à política e ao histórico do utilizador.

O endpoint do histórico de palavras-passe destina-se a cenários controlados de migração e recuperação. Também aceita entradas bcrypt com os mesmos limites de formato e custo e sem salt separado. A resposta detalhada contém material de hashes e PUT substitui todo o histórico. Aplique as mesmas proteções dos hashes importados e não registe os corpos dos pedidos ou respostas.

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 novos utilizadores ou substitui os correspondentes; não combina propriedades individuais nem pode alterar os identificadores de e-mail, telefone ou nome de utilizador. Trate-o como uma importação de substituição. Use a atualização individual para as alterações normais do ciclo de vida da conta quando for necessário preservar o estado existente e o ID de utilizador 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.

Bloqueios por falhas de início de sessão

Use as operações de lista e detalhe para examinar bloqueios e elimine um quando um administrador autorizar o seu fim.

Os bloqueios por utilizador têm um userIdentifier. Use esse valor e o tipo de falha para obter ou terminar um bloqueio. O filtro de lista filterUserIdentifier compara identificadores sem distinguir maiúsculas de minúsculas.

Os bloqueios DirectorySynchronisation têm um sequenceId e omitem userIdentifier. Use o sequenceId exato, sensível a maiúsculas, e o tipo de falha para obter ou terminar um bloqueio de sincronização, sem o parâmetro userIdentifier. Use filterSequenceId para encontrar bloqueios dessa sequência. Fornecer filterUserIdentifier e filterSequenceId encontra correspondências com qualquer um deles; o filtro de tipo de falha continua a aplicar-se a todos. O limite de pesquisas é partilhado por todos os identificadores da mesma sequência.

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.

Sessões personificadas

As sessões ativas mantêm os identificadores do utilizador autenticado original. Os detalhes de personificação identificam separadamente o target, incluindo subject, formato do subject, e-mail, telefone, nome de utilizador e referência de conta interna, quando disponíveis. Pode encontrar uma sessão ativa utilizando os identificadores de qualquer um dos utilizadores.

Os claims do token de atualização representam a identidade emitida à aplicação; os detalhes de personificação do grant identificam o utilizador autenticado original e o target selecionado. Ambas as contas associadas participam na revogação de acesso. Consulte personificação para a configuração do fluxo e o comportamento das sessões.

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