Directory Connector

Directory Connector permite ao FoxIDs usar um diretório externo como fonte autoritativa para as palavras-passe dos utilizadores internos e para dados selecionados do utilizador.

Os utilizadores continuam a existir como utilizadores internos no ambiente FoxIDs. Durante autenticação por palavra-passe e operações de ciclo de vida da palavra-passe, o FoxIDs chama a API de Directory Connector em vez de validar a palavra-passe apenas contra o utilizador interno do FoxIDs.

Como o FoxIDs mantém um registo interno do utilizador, a gestão de autenticação multifator (MFA) do FoxIDs pode ser adicionada aos utilizadores do repositório externo. O connector pode devolver definições de utilizador relacionadas com MFA, como requireMultiFactor e métodos two-factor desativados, e o FoxIDs aplica essas definições ao utilizador interno enquanto o repositório externo continua a ser autoritativo para palavras-passe e dados selecionados do utilizador.

Para Active Directory, o FoxIDs inclui um componente Directory Connector para Active Directory implementável em IIS.

Use Directory Connector quando:

  • Quer que os utilizadores iniciem sessão com o método de autenticação login normal.
  • Quer ativar utilizadores de um diretório existente para aplicações OpenID Connect e SAML 2.0 através do FoxIDs.
  • O seu diretório externo é autoritativo para validação de palavra-passe e alteração de palavra-passe.
  • Quer que o FoxIDs mantenha um registo interno do utilizador com identificadores, propriedades, claims, definições de autenticação multifator (MFA), atribuições de acesso e, opcionalmente, uma cópia local da palavra-passe.
  • Quer um caminho para mais tarde mudar para utilizadores internos e validação de palavra-passe no FoxIDs sem obrigar todos os utilizadores a fazer reset da palavra-passe.

Existe um único Directory Connector por ambiente. Quando está ativado, aplica-se ao nível do ambiente.

Como funciona

O FoxIDs sincroniza a pedido quando um utilizador introduz um identificador num fluxo de início de sessão ou recuperação. Chama synchronise-user antes de verificar a conta, cria um utilizador FoxIDs se necessário e atualiza os identificadores, propriedades e claims geridos pelo diretório.

A sincronização faz parte da ativação do Directory Connector. O FoxIDs sincroniza no início da autenticação, recuperação e verificações de contas de sessões existentes, e quando se utiliza um refresh token para uma conta ligada ao diretório. As continuações com códigos de confirmação, MFA e Extended UI usam a conta selecionada e as verificações normais do FoxIDs. Se a sincronização falhar, o fluxo para.

A resposta deve incluir um directoryUserId estável e único. Use o ID permanente da conta no diretório em vez de email, telefone ou nome de utilizador. Esta ligação permite ao FoxIDs encontrar a mesma conta após alterações nos identificadores. As aplicações de autenticação registadas e as atribuições de acesso FoxIDs são mantidas.

Quando o utilizador introduz um identificador, o FoxIDs envia apenas esse email, telefone ou nome de utilizador. Para reutilizar sessões e processar pedidos com refresh tokens, o FoxIDs carrega o utilizador associado e sincroniza através do ID do diretório guardado nesse utilizador. As operações de palavra-passe também usam o ID do utilizador carregado. Não é guardado separadamente na sequência de início de sessão.

O conector devolve todos os dados atuais do utilizador. O FoxIDs substitui os identificadores, propriedades e claims geridos pelo diretório, incluindo o estado de desativação, requisitos de alteração de palavra-passe e definições de configuração inicial. Aplica as mesmas verificações de conta, recuperação e MFA usadas para utilizadores internos. Utilizadores internos sem ligação ao diretório não são sincronizados nem associados automaticamente.

Uma resposta com disableAccount: true desativa o utilizador FoxIDs e revoga as sessões ativas e refresh-token grants. Se o conector devolver user_deleted ao sincronizar pelo ID do diretório, o FoxIDs elimina o utilizador interno e revoga sessões ativas e refresh tokens. Se uma pesquisa apenas por identificador não encontrar uma conta, o FoxIDs verifica qualquer ligação existente ao diretório antes de continuar, impedindo que dados locais desatualizados permitam autenticação ou recuperação. O código user_not_exists por si só não elimina uma conta.

Os pedidos com refresh tokens verificam a conta original e uma conta local usada por representação de identidade, quando ligadas ao diretório. Se a sincronização descobrir uma conta desativada ou eliminada, o FoxIDs revoga sessões ativas e refresh-token grants e rejeita a renovação atual. A verificação normal de sessões ativas valida o estado da sessão FoxIDs; não contacta diretamente o diretório. Uma aplicação que valida localmente um access token emitido respeita a sua expiração, não a revogação da sessão FoxIDs.

As alterações ficam disponíveis na próxima verificação de conta a pedido. Não existe um processo de sincronização em segundo plano.

O Directory Connector pode servir como integração permanente, com utilizadores e palavras-passe geridos no diretório externo, ou para os migrar gradualmente para o FoxIDs. Na migração, mantenha o conector ativo enquanto os utilizadores são criados e ative a cópia local da palavra-passe para guardar palavras-passe após autenticações, alterações ou reposições bem-sucedidas através do FoxIDs.

Após a migração, desative o Directory Connector e gira utilizadores e palavras-passe diretamente no FoxIDs. Antes da mudança, crie os utilizadores ainda não aprovisionados e prepare a definição ou recuperação de palavra-passe para quem não tenha uma cópia local atualizada. A cópia reflete a última autenticação, alteração ou reposição bem-sucedida através do FoxIDs; alterações posteriores feitas apenas no diretório externo não são incluídas.

Proteção das pesquisas

Quando o utilizador introduz email, telefone ou nome de utilizador na interface de autenticação ou recuperação, a pesquisa no diretório conta para um limite partilhado por todos os identificadores na sequência atual. O limite usa as definições do ambiente Failed login attempt limit, duração do contador e período de observação. Contam tanto pesquisas bem-sucedidas como chamadas falhadas; uma autenticação bem-sucedida por palavra-passe não reinicia o contador. Ao atingir o limite, é necessário aguardar o período de observação ou iniciar uma nova sequência. A sincronização para reutilização de sessões e pedidos com refresh tokens não usa este contador. A proteção de palavras-passe e códigos de confirmação mantém os contadores separados existentes.

Identificadores de início de sessão e associação ao diretório

Os utilizadores podem iniciar sessão com o email, telefone ou nome de utilizador atual, conforme os tipos ativados no método de início de sessão. Antes de autenticar a palavra-passe, o identificador introduzido deve corresponder a um identificador atual devolvido pelo conector. O FoxIDs remove espaços em redor da entrada. Email e nome de utilizador são comparados sem distinguir maiúsculas de minúsculas. Os telefones usam o formato internacional exigido.

Início de sessão após alterar identificadores

Quando um identificador é introduzido, o FoxIDs sincroniza email, telefone e nome de utilizador a partir do diretório. O ID estável mantém a ligação à mesma conta FoxIDs, mesmo que um ou todos os identificadores mudem. As aplicações de autenticação registadas e as atribuições de acesso são mantidas; as restrições de acesso e requisitos MFA existentes continuam a aplicar-se.

Situação O que acontece durante a sincronização
O utilizador inicia sessão com um nome de utilizador inalterado, mas o email ou telefone mudou no diretório. O FoxIDs atualiza a mesma conta com os identificadores atuais devolvidos pelo conector.
O utilizador inicia sessão com um identificador novo que o FoxIDs ainda não conhece. Se o diretório devolver o novo identificador e o mesmo ID estável, o utilizador continua com a conta FoxIDs existente. Funciona também quando todos os identificadores mudaram.
O utilizador inicia sessão com um identificador antigo que o conector já não devolve. O acesso é rejeitado com o erro habitual, mesmo que ainda conheça a palavra-passe. Deve usar um identificador atual de um tipo ativado.
O conector deixa de devolver um email, telefone ou nome de utilizador. Esse identificador é removido da conta FoxIDs durante a sincronização. O conector deve devolver pelo menos um identificador atual.

Por exemplo, um utilizador cujo email muda de old@example.org para new@example.org pode iniciar sessão com new@example.org antes de o FoxIDs conhecer esse endereço. O conector deve devolver new@example.org e o ID do diretório inalterado. O utilizador mantém a conta e as aplicações de autenticação registadas. Em alternativa, pode usar um nome de utilizador inalterado, se esta opção estiver ativada.

O conector deve devolver todos os identificadores atuais a manter no FoxIDs. Valores omitidos ou vazios são tratados como identificadores removidos; os valores anteriores não são conservados como aliases de acesso. Só podem ser usados tipos ativados no método de início de sessão.

Conflitos de contas

Cada utilizador do diretório deve ter um ID estável e único; os seus identificadores não podem pertencer a outra conta FoxIDs. O FoxIDs pesquisa primeiro o identificador no diretório, depois usa o ID devolvido para encontrar ou criar a conta local. Se guardar os identificadores gerar um conflito com outra conta, o fluxo para. Um administrador deve corrigir a configuração do diretório ou da conta FoxIDs; as contas não são fundidas nem reatribuídas automaticamente.

Um utilizador interno existente sem ligação ao diretório não pode iniciar sessão através do Directory Connector. Ativá-lo não associa automaticamente uma conta a um utilizador do diretório apenas porque email, telefone ou nome de utilizador coincidem.

Cópia local da palavra-passe

O diretório externo é autoritativo enquanto Directory Connector estiver ativado. O FoxIDs não faz fallback para o hash local da palavra-passe se a API de Directory Connector estiver temporariamente indisponível.

Por predefinição, o FoxIDs guarda uma cópia local da palavra-passe no utilizador interno após uma validação de palavra-passe bem-sucedida pelo connector ou após uma operação de ciclo de vida da palavra-passe. Isto pode ser desativado nas definições do ambiente.

A cópia local da palavra-passe não é usada enquanto Directory Connector estiver ativado. Existe para suportar uma mudança futura para utilizadores internos e validação de palavra-passe no FoxIDs sem obrigar todos os utilizadores a fazer reset da palavra-passe.

Ciclo de vida da palavra-passe

A criação de utilizadores e as operações do ciclo de vida da palavra-passe são delegadas à API de Directory Connector:

  • A autenticação por palavra-passe chama o endpoint authentication.
  • A criação de utilizadores no fluxo de início de sessão chama o endpoint create-user.
  • A alteração de palavra-passe do utilizador chama o endpoint change-password.
  • Os fluxos set-password e reset-password chamam o endpoint set-password.

Os endpoints de palavra-passe recebem o directoryUserId estável do utilizador carregado. O diretório verifica o estado atual da conta e as credenciais durante a operação. Autenticação, alteração e reposição devolvem sucesso ou erro. A criação devolve o ID do diretório da conta criada, usado pelo FoxIDs numa sincronização separada.

As operações de palavra-passe usam o ID do diretório guardado no utilizador FoxIDs carregado. O conector verifica o estado da conta e as credenciais ou autorização de reposição necessárias, executa a ação e devolve sucesso ou erro. Identificadores, atributos e claims só são devolvidos pela sincronização.

Após uma alteração ou reposição bem-sucedida, o FoxIDs regista a hora atual da alteração e remove os requisitos de alterar ou definir uma palavra-passe. Guarda também uma cópia local, se configurado. A sequência ativa continua com a gestão normal da conta, recuperação e MFA.

Se uma ação falhar ou o FoxIDs não conseguir guardar as alterações conhecidas da palavra-passe, o fluxo para. Uma alteração já aceite pelo diretório não é revertida e o FoxIDs não repete automaticamente a ação após tempo limite ou resposta falhada. A próxima sincronização atualiza a conta local.

Com Enable password policy ativado, o FoxIDs verifica a palavra-passe atual do diretório antes de aplicar as verificações à nova. Isto pode exigir uma chamada de autenticação adicional antes de change-password.

O FoxIDs não atualiza o seu histórico interno de palavras-passe quando Directory Connector é usado, porque o FoxIDs não conhece necessariamente todas as alterações de palavra-passe no diretório externo.

Definição e recuperação de palavras-passe

No primeiro início de sessão, um utilizador do diretório pode definir uma palavra-passe com um código de confirmação por email ou SMS, porque a esqueceu ou tem de escolher uma nova.

Para usar Forgot your password?, introduza um identificador atual do diretório de um tipo ativado no método de acesso. O FoxIDs sincroniza e cria a conta antes de enviar o código. A recuperação por email ou SMS deve estar ativada e o utilizador deve ter acesso ao contacto atual devolvido pelo diretório.

Após verificar o código e submeter uma nova palavra-passe, o FoxIDs chama set-password com o ID estável. Devolva setPasswordEmail ou setPasswordSms e o identificador de contacto correspondente para exigir este fluxo de definição. O FoxIDs usa o seu fluxo habitual.

Os códigos de confirmação estão ligados à conta para a qual foram emitidos. As contas geridas por um conector de diretório usam a mesma verificação de códigos dos restantes utilizadores internos. O FoxIDs mantém o tratamento normal de erros de recuperação sem expor diagnósticos do conector.

Política de palavra-passe e mensagens de erro

O diretório externo impõe a política de palavra-passe. O FoxIDs usa a política de palavra-passe do ambiente quando mostra mensagens de erro de política de palavra-passe devolvidas pelo connector.

Configure a política de palavra-passe do ambiente para corresponder à política de palavra-passe do diretório externo. Se não corresponderem, os utilizadores podem ver orientação sobre palavras-passe que não reflete os requisitos reais do diretório externo.

Por exemplo, se o diretório externo rejeitar uma palavra-passe por ser demasiado curta, o FoxIDs usa o comprimento mínimo da palavra-passe do ambiente ao renderizar a mensagem de erro.

Implementar API

Implementa uma API de Directory Connector e configura o FoxIDs com o URL base e o secret dessa API.

A API tem um URL base e cinco endpoints:

  • synchronise-user pesquisa um utilizador e devolve o estado atual da conta, identificadores e claims.
  • authentication valida a palavra-passe atual de um utilizador.
  • create-user cria um utilizador no diretório externo e devolve o seu ID permanente.
  • change-password valida a palavra-passe atual e altera-a para uma nova palavra-passe.
  • set-password define uma nova palavra-passe sem validar a palavra-passe atual.

Se o URL base for https://somewhere.org/directory, os endpoints são:

  • https://somewhere.org/directory/synchronise-user
  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/create-user
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

O FoxIDs Cloud chama a sua API a partir do IP 57.128.60.142. O(s) IP(s) podem mudar ou ser expandidos.

Segurança

Os pedidos são protegidos com HTTP Basic authentication:

  • Username: directory_connector
  • Password: o secret configurado da API

A chamada é HTTP POST com um body JSON.

O FoxIDs envia o idioma selecionado no cabeçalho Accept-Language, por exemplo Accept-Language: da-DK. No acesso, segue o idioma escolhido por ui_locales ou pelo browser, usando inglês como alternativa FoxIDs. A API pode usar o cabeçalho para localizar mensagens e deve escolher a sua própria alternativa se não suportar o idioma pedido. O cabeçalho é enviado aos cinco endpoints.

Pedido de sincronização

O endpoint synchronise-user recebe um identificador de utilizador ou um ID conhecido do diretório. A primeira pesquisa no acesso ou recuperação usa o identificador introduzido. O FoxIDs usa o directoryUserId guardado nas verificações de sessões existentes e pedidos com refresh tokens, e o ID devolvido após create-user.

Uma pesquisa inicial por email:

{
  "email": "user1@somewhere.org"
}

Uma verificação posterior da conta:

{
  "directoryUserId": "a1b2c3d4"
}

Use directoryUserId como chave de pesquisa autoritativa quando presente. Caso contrário, pesquise exatamente um de email, phone ou username. Devolva HTTP 200 com todos os dados do utilizador, incluindo contas desativadas. Devolva user_deleted se faltar o ID conhecido e user_not_exists se uma pesquisa apenas por identificador não encontrar uma conta. Um identificador fornecido nunca prova a propriedade da conta.

O FoxIDs escolhe o identificador do pedido conforme os tipos de acesso ativados. Se apenas o nome de utilizador estiver ativo, uma entrada em formato de email é enviada como username. Os espaços em redor são removidos. A entrada deve corresponder a um identificador atual de um tipo ativado na resposta; o campo presumido do pedido não limita qual campo da resposta pode corresponder.

Para erros, consulte Resposta de erro.

Resposta em caso de sucesso

O endpoint synchronise-user devolve HTTP 200 com todos os dados atuais do utilizador. Se o pedido fornecer um ID do diretório, a resposta deve conter o mesmo. O FoxIDs verifica-o antes de guardar dados. HTTP 204 ou dados incompletos são rejeitados.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "emailVerified": true,
  "phoneVerified": true,
  "disableTwoFactorApp": false,
  "disableTwoFactorSms": false,
  "disableTwoFactorEmail": false,
  "requireMultiFactor": false,
  "claims": [
    { "type": "name", "value": "User One" },
    { "type": "role", "value": "employee" }
  ]
}

O FoxIDs usa a resposta para criar ou atualizar o utilizador interno no ambiente.

Campos:

  • directoryUserId é obrigatório. Tem de ser estável e único no diretório externo e é guardado no utilizador interno do FoxIDs.
  • email, phone e username são opcionais individualmente, mas pelo menos um tem de estar presente. O FoxIDs guarda os valores devolvidos como identificadores do utilizador interno. Os valores de identificador de utilizador devolvidos têm de identificar de forma única um único utilizador no diretório externo usado pelo connector.
  • phone tem de incluir o indicativo do país em formato internacional, por exemplo +4511223344.
  • confirmAccount controla se o FoxIDs deve executar um fluxo de confirmação para confirmar o utilizador interno.
  • disableAccount controla diretamente o estado de desativação. A passagem a desativado revoga as sessões FoxIDs e os refresh-token grants do utilizador.
  • changePassword exige a alteração da palavra-passe após verificar as credenciais com sucesso.
  • setPasswordEmail e setPasswordSms exigem definir a palavra-passe pelo fluxo de confirmação correspondente. O identificador de contacto deve existir e o método de recuperação deve estar ativado.
  • disableSetPasswordEmail e disableSetPasswordSms desativam os métodos de recuperação correspondentes.
  • passwordLastChanged é um timestamp Unix opcional, não negativo, em segundos. Fornecido pela sincronização, atualiza a idade da palavra-passe usada pelo FoxIDs. Se omitido, o timestamp existente é mantido. Uma alteração ou reposição bem-sucedida regista a hora atual no FoxIDs; uma sincronização posterior pode fornecer o timestamp autoritativo do diretório.
  • emailVerified controla se o email do utilizador interno é marcado como verificado.
  • phoneVerified controla se o número de telefone do utilizador interno é marcado como verificado.
  • disableTwoFactorApp desativa autenticação de dois fatores com app autenticadora para o utilizador interno.
  • disableTwoFactorSms desativa autenticação de dois fatores por SMS para o utilizador interno.
  • disableTwoFactorEmail desativa autenticação de dois fatores por email para o utilizador interno.
  • requireMultiFactor controla se o utilizador interno tem de usar autenticação multifator.
  • claims é opcional. O FoxIDs guarda os claims devolvidos no utilizador interno.

O FoxIDs ignora os claims cujo type ou value está em falta, é null, está vazio ou contém apenas espaços em branco. Com o rastreio de mensagens de registo ativado, o rastreio da resposta inclui os claims recebidos antes de serem filtrados. As mensagens de rastreio longas são truncadas.

Os claims protegidos, como sid e auth_time, também são removidos das respostas de sincronização.

Pedido de autenticação

O endpoint authentication recebe o ID estável obrigatório do diretório e a palavra-passe atual.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Verifique o estado atual da conta no diretório e a palavra-passe antes de devolver sucesso. Verifique a palavra-passe antes de fornecer indicações de política específicas da conta.

Para erros, consulte Resposta de erro.

Resposta em caso de sucesso

Em caso de sucesso, devolva HTTP 204 sem corpo de resposta.

Pedido de criação de utilizador

O endpoint create-user recebe exatamente um identificador de utilizador, uma palavra-passe obrigatória, as propriedades create-user selecionadas e os claims recolhidos durante o fluxo create-user do FoxIDs.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Campos:

  • Exatamente um de email, phone ou username é enviado.
  • password é obrigatório. Criar utilizador sem palavra-passe não é suportado com Directory Connector, porque a API Directory Connector autentica utilizadores com palavra-passe.
  • confirmAccount e requireMultiFactor são as definições solicitadas para a criação do utilizador no FoxIDs.
  • claims contém os claims que não são identificadores, recolhidos durante a criação do utilizador no FoxIDs.

Para erros, consulte Resposta de erro.

Resposta em caso de sucesso

Em caso de sucesso, devolva HTTP 200 com o ID permanente da conta criada:

{
  "directoryUserId": "a1b2c3d4"
}

O FoxIDs chama depois synchronise-user com este ID para obter a conta completa e criar o utilizador interno FoxIDs.

Pedido de change-password

O endpoint change-password recebe o ID obrigatório do diretório e as palavras-passe atual e nova. Verifique a atual antes de devolver indicações de política específicas da conta.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Para erros, consulte Resposta de erro.

Resposta em caso de sucesso

Em caso de sucesso, devolva HTTP 204 sem corpo. A alteração deve satisfazer o requisito de palavra-passe do diretório.

Pedido de set-password

O endpoint set-password recebe o ID obrigatório do diretório e a nova palavra-passe. O FoxIDs chama-o após autorizar a reposição ou definição, incluindo verificação de códigos nos fluxos de recuperação. O conector deve voltar a verificar o estado atual da conta antes de alterar a palavra-passe.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Para erros, consulte Resposta de erro.

Resposta em caso de sucesso

Em caso de sucesso, devolva HTTP 204 sem corpo. A reposição ou definição deve satisfazer o requisito de palavra-passe do diretório.

Resposta de erro

Todos os endpoints usam o mesmo formato de erro JSON. Devolva um código suportado pelo endpoint em error e detalhes de diagnóstico em errorMessage. Por exemplo, uma palavra-passe rejeitada por authentication:

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Use estes códigos de estado HTTP:

  • 401 com invalid_api_id_secret quando a autenticação HTTP Basic é rejeitada.
  • 400, 401 ou 403 para os restantes códigos suportados na tabela abaixo.
  • 500 para uma falha técnica do conector.

O campo errorMessage contém texto de diagnóstico para os registos do FoxIDs e não é mostrado ao utilizador final. Indique a causa da falha, mas nunca inclua palavras-passe, segredos da API ou chaves privadas.

Só authentication pode devolver login_rejected, após verificar identificador e palavra-passe. Pode incluir um uiErrorMessage opcional, apresentado pelo FoxIDs como texto simples no formulário de acesso. A API fornece a mensagem no idioma escolhido através de Accept-Language:

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Se uiErrorMessage for omitido, null, vazio ou contiver apenas espaços, o FoxIDs mostra a mesma mensagem geral localizada de invalid_password e operation_rejected. Para outros códigos suportados, ignora uiErrorMessage e escolhe a mensagem dos seus próprios textos localizados. O diagnóstico errorMessage nunca é usado como alternativa a uma mensagem para o utilizador. Consulte Erros de autenticação e privacidade para os requisitos de verificação.

Os erros de authentication, change-password e set-password não devolvem dados do utilizador, não alteram a conta interna nem revogam sessões ou refresh tokens existentes. A sincronização aplica as alterações do diretório. As tentativas rejeitadas de autenticação e alteração de palavra-passe continuam a contar para o limite de acessos falhados existente.

Códigos de erro suportados por endpoint:

Código de erro synchronise-user authentication create-user change-password set-password Significado
invalid_api_id_secret Sim Sim Sim Sim Sim O nome de utilizador ou o segredo da API para HTTP Basic authentication é inválido.
user_exists Não Não Sim Não Não Já existe um utilizador com o identificador fornecido no diretório externo.
user_not_exists Sem ID do diretório Não Não Não Não Nenhum utilizador do diretório corresponde à pesquisa apenas por identificador.
invalid_password Não Sim Não Não Não O diretório rejeitou a palavra-passe num pedido de autenticação.
login_rejected Não Sim Não Não Não O início de sessão foi rejeitado após a verificação do identificador de utilizador e da palavra-passe. É apresentado um uiErrorMessage opcional no formulário de início de sessão.
invalid_current_password Não Não Não Sim Não O diretório rejeitou a palavra-passe atual num pedido de alteração de palavra-passe.
create_user_not_supported Não Não Sim Não Não O conector não suporta a criação de utilizadores no diretório externo.
operation_rejected Não Sim Não Sim Sim A operação não pode ser concluída, por exemplo porque a conta está indisponível. O FoxIDs regista errorMessage, ignora uiErrorMessage e mostra um erro geral localizado sem alterar o estado da conta.
user_deleted Com ID do diretório Não Não Não Não Um ID conhecido já não existe. O FoxIDs revoga o acesso e elimina o utilizador durante a sincronização.
password_not_accepted Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida foi rejeitada por uma regra de palavras-passe do diretório que não corresponde a um código mais específico.
password_min_length Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida é mais curta do que o comprimento mínimo das palavras-passe do diretório.
password_max_length Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida é mais longa do que o comprimento máximo das palavras-passe do diretório.
password_banned_characters Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém um ou mais caracteres ou palavras rejeitados pelo diretório.
password_complexity Não Sim Sim Sim Sim Erro antigo de complexidade de caracteres que o FoxIDs interpreta como password_character_variation. Utilize um dos dois códigos de erro específicos de caracteres nas novas integrações.
password_character_repeat Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém demasiadas repetições de caracteres.
password_character_variation Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida não contém uma variedade suficiente de caracteres.
password_email_text_complexity Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém o endereço de e-mail do utilizador ou parte do mesmo.
password_phone_text_complexity Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém o número de telefone do utilizador ou parte do mesmo.
password_username_text_complexity Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém o nome de utilizador ou parte do mesmo.
password_url_text_complexity Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida contém texto relacionado com o URL do FoxIDs.
password_risk Não Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida é reconhecida como arriscada, comprometida ou insegura por outro motivo.
password_history Não Não Não Sim Sim A nova palavra-passe foi rejeitada por já ter sido utilizada.
password_expired Não Sim Não Não Não A palavra-passe fornecida foi verificada mas expirou; o utilizador deve alterá-la antes de continuar a autenticação.
new_password_equals_current Não Não Não Sim Não A nova palavra-passe é igual à atual. set-password não pode devolver este erro porque não recebe a palavra-passe atual.

Se o FoxIDs precisar de verificar a sua política antes de uma alteração, chama primeiro authentication para verificar a palavra-passe atual. Se o conector devolver password_expired nessa autenticação, a alteração pode continuar. O endpoint change-password deve aceitar uma palavra-passe atual expirada mas verificada e devolver apenas erros suportados para a alteração.

Para erros de política de palavra-passe, o FoxIDs usa a política de palavra-passe do ambiente para mostrar a mensagem de erro voltada para o utilizador. Veja Política de palavra-passe e mensagens de erro.

Devolva apenas códigos suportados pelo endpoint e pelo directoryUserId fornecido, conforme indicado acima. Um código não suportado, resposta malformada ou estado HTTP inesperado é uma falha de integração e conduz à página de erro geral. Consulte Resolução de erros do browser para encontrar diagnósticos através dos identificadores da página de erro.

Erros de autenticação e privacidade dos utilizadores

Um chamador não autenticado não deve conseguir determinar se existe um nome de utilizador ou um endereço de e-mail a partir de uma falha de início de sessão. Durante a autenticação por palavra-passe, o FoxIDs trata os erros suportados da seguinte forma:

Erro do conector Resultado para o utilizador
invalid_password, operation_rejected ou uma conta indisponível detetada durante a sincronização A mesma mensagem genérica de início de sessão, como E-mail ou palavra-passe errados., traduzida para o idioma ativo e adaptada aos identificadores de início de sessão ativados.
login_rejected O uiErrorMessage fornecido, ou a mesma mensagem genérica de início de sessão se estiver em falta ou vazio, no mesmo local do formulário de início de sessão.
password_not_accepted A página de alteração da palavra-passe com orientações gerais sobre a política de palavras-passe.
password_expired ou outro erro específico da política de palavras-passe A página de alteração da palavra-passe com as orientações localizadas correspondentes à política de palavras-passe.

O conector tem de verificar a palavra-passe atual fornecida antes de devolver um erro da política de palavras-passe de authentication. Caso contrário, uma página ou mensagem diferente pode permitir que um atacante descubra utilizadores e confirme os respetivos identificadores ao tentar adivinhar nomes de utilizador ou endereços de e-mail. Em change-password, verifique a palavra-passe atual antes de devolver orientações específicas da conta sobre a nova palavra-passe. As verificações gerais de formato não devem revelar se uma conta existe.

Se um utilizador não puder usar este fluxo por qualquer motivo, valide primeiro o identificador e a palavra-passe fornecidos. Rejeite com base na restrição apenas depois de verificar ambos, para não revelar se um identificador adivinhado pertence a um utilizador real. Devolva login_rejected de authentication, indique a razão diagnóstica em errorMessage e, opcionalmente, informação segura em uiErrorMessage. Se as credenciais não puderem ser verificadas, devolva a falha habitual sem revelar a restrição.

O FoxIDs confia no conector para verificar as credenciais antes de devolver login_rejected; uma pesquisa bem-sucedida ou conhecer directoryUserId não basta. Antes da verificação, apresente instruções ou botões para métodos alternativos independentemente de o identificador corresponder a uma conta.

Só synchronise-user comunica o estado da conta: devolva todos os dados com disableAccount: true para uma conta desativada, ou user_deleted quando um ID conhecido já não existir. Os endpoints de palavra-passe devolvem operation_rejected se a conta estiver indisponível. Ao contrário de login_rejected, não exige uma palavra-passe verificada porque nunca fornece ao browser indicações específicas da conta.

Trate as falhas de forma consistente para identificadores conhecidos e desconhecidos, incluindo os tempos de resposta observáveis e a proteção contra tentativas repetidas. Uma mensagem genérica, por si só, não impede a descoberta de utilizadores se um redirecionamento, um estado ou um tempo de resposta diferente revelar o resultado. Siga as orientações da OWASP sobre erros de autenticação ao implementar o conector.

Exemplo de API

O sample DirectoryConnectorApiSample mostra como implementar a API de Directory Connector em ASP.NET Core.

Implementações e clientes de teste devem seguir os contratos acima: HTTP 200 com dados completos do utilizador para synchronise-user, HTTP 200 com o ID criado para create-user e HTTP 204 sem corpo para operações de palavra-passe bem-sucedidas.

Componente Active Directory

O FoxIDs inclui um Directory Connector para Active Directory implementável em IIS. O componente implementa a API para um domínio AD/LDAP e pode sincronizar contas, validar, alterar e definir palavras-passe, e devolver atributos AD e pertenças a grupos AD aninhados configurados como claims.

Configurar

Configure o Directory Connector nas definições do ambiente em FoxIDs Control Client.

  1. Selecione o separador Definições.
  2. Selecione o separador Ambiente.
  3. Encontre a secção Directory Connector.
  4. Ative Directory Connector.
  5. Adicione o URL base da API sem a pasta do endpoint em API URL.
  6. Adicione o API secret.
  7. Decida se quer guardar uma cópia local da palavra-passe.
  8. Configure a política de palavra-passe do ambiente para corresponder à política de palavra-passe do diretório externo.
  9. Clique em Update.

Directory Connector settings