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.

Use Directory Connector quando:

  • Quer que os utilizadores iniciem sessão com o método de autenticação login normal.
  • 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 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.
  • 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 só chama os endpoints de ciclo de vida da palavra-passe quando o utilizador interno é conhecido e tem um directoryUserId. Isto impede que o FoxIDs chame o diretório externo sem o vínculo estável ao utilizador externo.

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.

A API tem um URL base e três endpoints:

  • authentication valida a palavra-passe atual de um utilizador.
  • 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/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.

Pedido de change-password

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

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

Campos:

  • directoryUserId é enviado e deve ser usado como vínculo estável ao diretório.
  • 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,
  "disableAccount": false,
  "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 individualmente opcionais, mas pelo menos um tem de estar presente. O FoxIDs guarda os valores devolvidos como identificadores do utilizador interno.
  • 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.
  • disableAccount controla se o utilizador interno é desativado no FoxIDs após sincronização.
  • 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 a combinação username/password for rejeitada pelo endpoint authentication, devolva HTTP status code 400, 401 ou 403 e invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or 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.

Códigos de erro suportados:

  • invalid_username_password - A combinação de identificador de utilizador e palavra-passe foi rejeitada pelo diretório.
  • invalid_current_password - A palavra-passe atual num pedido change-password foi rejeitada pelo diretório.
  • user_disabled - O utilizador existe no diretório mas está desativado. O FoxIDs irá desativar o utilizador interno.
  • user_deleted - O utilizador já não existe ou foi eliminado no diretório. O FoxIDs irá eliminar o utilizador interno.
  • password_not_accepted - A nova palavra-passe foi rejeitada por uma regra de palavra-passe do diretório que não mapeia para um código mais específico.
  • password_min_length - A nova palavra-passe é mais curta do que o comprimento mínimo definido no diretório.
  • password_max_length - A nova palavra-passe é mais longa do que o comprimento máximo definido no diretório.
  • password_banned_characters - A nova palavra-passe contém um ou mais caracteres ou palavras rejeitados pelo diretório.
  • password_complexity - A nova palavra-passe não satisfaz os requisitos de complexidade do diretório.
  • password_email_text_complexity - A nova palavra-passe contém o email do utilizador ou parte dele.
  • password_phone_text_complexity - A nova palavra-passe contém o número de telefone do utilizador ou parte dele.
  • password_username_text_complexity - A nova palavra-passe contém o username do utilizador ou parte dele.
  • password_url_text_complexity - A nova palavra-passe contém texto relacionado com o URL do FoxIDs.
  • password_risk - A nova palavra-passe é conhecida como arriscada, comprometida ou insegura.
  • password_history - A nova palavra-passe foi rejeitada porque já foi usada antes.
  • password_expired - A palavra-passe atual expirou e tem de ser alterada antes de a autenticação poder continuar.
  • new_password_equals_current - A nova palavra-passe é igual à palavra-passe atual.

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, 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 Active Directory Directory Connector 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