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

Quando um utilizador inicia sessão com username e password, o FoxIDs chama a API de Directory Connector.

Em caso de validação bem-sucedida, o FoxIDs cria ou atualiza o utilizador interno no ambiente com base na resposta da API. A resposta tem de incluir um directoryUserId estável, que é guardado no utilizador interno e usado para ligar o utilizador FoxIDs ao utilizador do diretório externo.

O directoryUserId não é um identificador de utilizador conhecido pelo utilizador final. É um ID separado e estável do diretório externo. Não use email, telefone ou username como directoryUserId, porque esses valores podem mudar. O valor tem de ser estável e único no diretório externo.

Se o FoxIDs já conhecer o directoryUserId do utilizador interno, esse valor é enviado no pedido de Directory Connector juntamente com exatamente um dos identificadores do utilizador: email, telefone ou username. Isto permite ao diretório externo identificar o utilizador mesmo que um identificador tenha mudado.

Se a API de Directory Connector validar o utilizador com sucesso, o FoxIDs atualiza o utilizador interno com identificadores, propriedades selecionadas e claims devolvidos pela API.

Se o connector indicar que o utilizador está desativado ou eliminado, o FoxIDs irá desativar ou eliminar o utilizador interno no ambiente.

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

As operações de ciclo de vida da palavra-passe são delegadas para a API de Directory Connector:

  • A autenticação por palavra-passe chama o endpoint authentication.
  • Login create-user flow calls the create-user endpoint.
  • 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.

O FoxIDs normalmente só chama os endpoints de ciclo de vida da palavra-passe quando o utilizador interno é conhecido e tem um directoryUserId. A exceção é change-password durante o primeiro início de sessão, quando o diretório externo devolveu password_expired antes de o FoxIDs ter criado o utilizador interno. Nesse caso, o FoxIDs envia o identificador de início de sessão e a palavra-passe atual sem directoryUserId; após uma alteração de palavra-passe bem-sucedida, o FoxIDs usa a resposta de sucesso para criar o utilizador interno e guardar o directoryUserId devolvido.

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.

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.

The API has a base URL and four endpoints:

  • authentication valida a palavra-passe atual de um utilizador.
  • create-user creates a new user in the external directory and returns the created user.
  • 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/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.

Pedido de autenticação

O endpoint authentication recebe a palavra-passe do utilizador e exatamente um identificador de utilizador. O FoxIDs envia directoryUserId se o utilizador interno existir e o valor for conhecido.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Campos:

  • directoryUserId é opcional. O FoxIDs envia-o quando o utilizador interno existe e o valor é conhecido.
  • Exatamente um de email, phone ou username é enviado.
  • password é obrigatório.

O FoxIDs seleciona o identificador com base na entrada de login do utilizador e nas definições de identificador ativadas. Por exemplo, se apenas username estiver ativado e o utilizador introduzir user1@somewhere.org, o FoxIDs envia-o como username.

Create-user request

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" }
  ]
}

Fields:

  • Exactly one of email, phone, or username is sent.
  • 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 and requireMultiFactor are the requested FoxIDs create-user settings.
  • claims contains the non-identifier claims collected during the FoxIDs create-user flow.

On success, return a normal success response. FoxIDs stores the returned directoryUserId on the internal user created after the external directory user has been created.

Pedido de change-password

O endpoint change-password recebe exatamente um identificador de utilizador, a palavra-passe atual e a nova palavra-passe. O FoxIDs envia directoryUserId quando o utilizador interno existe e o valor é conhecido.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Campos:

  • directoryUserId é opcional. O FoxIDs envia-o quando o utilizador interno existe e o valor é conhecido. Pode ser omitido durante o primeiro início de sessão se o diretório externo exigir uma alteração de palavra-passe antes de o FoxIDs ter criado o utilizador interno.
  • Exatamente um de email, phone ou username é enviado.
  • currentPassword e newPassword são obrigatórios.

Pedido de set-password

O endpoint set-password recebe o vínculo estável do utilizador ao diretório, exatamente um identificador de utilizador e a nova palavra-passe.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Campos:

  • directoryUserId é enviado e deve ser usado como vínculo estável ao diretório.
  • Exatamente um de email, phone ou username é enviado. O FoxIDs seleciona o primeiro identificador interno disponível por esta ordem: email, telefone, username.
  • password é obrigatório.

Resposta de sucesso

Em caso de sucesso, a API tem de devolver HTTP status code 200 e uma resposta de utilizador.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "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.
  • 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.

Resposta de erro

Se a autenticação Basic for rejeitada, devolva HTTP status code 401 e invalid_api_id_secret.

{
  "error": "invalid_api_id_secret",
  "errorMessage": "Invalid API ID or secret."
}

Se o utilizador não existir ao chamar o endpoint authentication, devolva HTTP status code 400, 401 ou 403 e user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Se a password for rejeitada pelo endpoint authentication, devolva HTTP status code 400, 401 ou 403 e invalid_password.

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

Se a palavra-passe atual for rejeitada pelo endpoint change-password, devolva HTTP status code 400, 401 ou 403 e invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

O campo errorMessage é registado pelo FoxIDs e não é mostrado ao utilizador final.

Supported error codes by endpoint:

Error code authentication create-user change-password set-password Meaning
invalid_api_id_secret Yes Yes Yes Yes The HTTP Basic API username or secret is invalid.
user_exists No Yes No No A user with the supplied identifier already exists in the external directory.
user_not_exists Yes, without DirectoryUserId No Yes, without DirectoryUserId No No external directory user matched the supplied user identifiers.
invalid_password Yes No No No The password in an authentication request was rejected by the directory.
invalid_current_password No No Yes No The current password in a change-password request was rejected by the directory.
create_user_not_supported No Yes No No The connector does not support creating users in the external directory.
user_disabled Yes No Yes Yes The user exists in the directory but is disabled. FoxIDs will disable the internal user.
user_deleted Yes, with DirectoryUserId No Yes, with DirectoryUserId Yes, with DirectoryUserId The external directory user linked by DirectoryUserId no longer exists or is deleted. FoxIDs will delete the internal user.
password_not_accepted Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected by a directory password rule that does not map to a more specific code.
password_min_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is shorter than the directory password minimum length.
password_max_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is longer than the directory password maximum length.
password_banned_characters Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains one or more characters or words rejected by the directory.
password_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set does not satisfy the directory complexity requirements.
password_email_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's email or part of it.
password_phone_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's phone number or part of it.
password_username_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's username or part of it.
password_url_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains text related to the FoxIDs URL.
password_risk Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is known to be risky, compromised, or otherwise unsafe.
password_history Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected because it has been used before.
password_expired Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is expired and must be changed before authentication can continue.
new_password_equals_current No No Yes No The new password is the same as the current password. set-password cannot return this error because it does not receive the current password.

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.

Se ocorrerem outros erros, devolva HTTP status code 500 ou outro código de erro apropriado. Inclua um errorMessage técnico quando for útil para diagnóstico.

Exemplo de API

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

O sample inclui:

  • Os endpoints authentication, create-user, change-password e set-password.
  • HTTP Basic authentication com o username da API directory_connector.
  • Um pequeno diretório em memória com utilizadores de demonstração e valores estáveis de directoryUserId.
  • Exemplos de erros de política de palavra-passe, como password_min_length, password_banned_characters e new_password_equals_current.
  • Um exemplo de utilizador desativado que devolve user_disabled.

Postman collection directory-connector-api.postman_collection.json pode ser usada para chamar e testar a API sample com Postman.

Componente Active Directory

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

Configurar

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

  1. Selecione o separador Settings.
  2. Selecione o separador Environment.
  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

A sua privacidade

A sua privacidade

Usamos cookies para melhorar a sua experiência nos nossos sites. Clique no botão 'Aceitar todos os cookies' para concordar com a utilização de cookies. Para recusar cookies não essenciais, clique em 'Apenas cookies necessários'.

Visite a nossa página de Política de Privacidade para saber mais