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.

O FoxIDs envia o idioma selecionado no cabeçalho do pedido Accept-Language, por exemplo Accept-Language: da-DK. Num fluxo de início de sessão, corresponde ao idioma selecionado através de ui_locales ou do navegador, com o inglês como idioma de recurso no FoxIDs. A API pode utilizar este cabeçalho para localizar as mensagens apresentadas ao utilizador e tem de escolher o seu próprio idioma de recurso se não suportar o idioma solicitado. Este cabeçalho é enviado para os quatro endpoints.

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. O FoxIDs remove os espaços em branco circundantes antes de enviar o username para o connector.

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

Campos:

  • É enviado exatamente um dos campos email, phone ou username.
  • 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.

Em caso de sucesso, devolva uma resposta de sucesso normal. O FoxIDs guarda o directoryUserId devolvido no utilizador interno criado após a criação do utilizador no diretório externo.

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.

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.

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 sem um directoryUserId, devolva o código de estado HTTP 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 o identificador de utilizador e a palavra-passe forem válidos, mas o início de sessão for rejeitado por outro motivo, devolva o código de estado HTTP 400, 401 ou 403 e login_rejected de authentication. É suportado com ou sem directoryUserId. O campo opcional uiErrorMessage é apresentado como texto simples no formulário de início de sessão. A API fornece a mensagem traduzida com base em 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, for null, estiver vazio ou contiver apenas caracteres de espaço em branco, o FoxIDs apresenta a mesma mensagem genérica de início de sessão localizada que para invalid_password, user_not_exists, user_disabled e user_deleted. Um início de sessão rejeitado é contabilizado na proteção existente contra tentativas de início de sessão falhadas repetidas. Não cria, atualiza, desativa nem elimina o utilizador interno.

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 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.

O FoxIDs apresenta um uiErrorMessage devolvido apenas para login_rejected. Para os restantes códigos de erro suportados, o FoxIDs seleciona a mensagem apresentada ao utilizador a partir dos seus próprios recursos de texto localizados. O texto de diagnóstico em errorMessage nunca é utilizado como alternativa a uma mensagem apresentada ao utilizador.

Códigos de erro suportados por endpoint:

Código de erro authentication create-user change-password set-password Significado
invalid_api_id_secret Sim Sim Sim Sim O nome de utilizador ou o segredo da API para HTTP Basic authentication é inválido.
user_exists Não Sim Não Não Já existe um utilizador com o identificador fornecido no diretório externo.
user_not_exists Sim, sem directoryUserId Não Sim, sem directoryUserId Não Nenhum utilizador no diretório externo corresponde aos identificadores de utilizador fornecidos.
invalid_password Sim Não Não Não O diretório rejeitou a palavra-passe num pedido de autenticação.
login_rejected 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 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 Sim Não Não O conector não suporta a criação de utilizadores no diretório externo.
user_disabled Sim Não Sim Sim O utilizador existe no diretório, mas está desativado. O FoxIDs desativa o utilizador interno.
user_deleted Sim, com directoryUserId Não Sim, com directoryUserId Sim, com directoryUserId O utilizador do diretório externo associado através de directoryUserId já não existe ou foi eliminado. O FoxIDs elimina o utilizador interno.
password_not_accepted 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 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 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 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 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 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 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 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 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 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 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 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 Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida foi rejeitada porque já foi utilizada anteriormente.
password_expired Sim Sim Sim Sim A palavra-passe que é validada, utilizada para criar um utilizador, alterada ou definida expirou e tem de ser alterada antes de a autenticação poder continuar.
new_password_equals_current 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.

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 um código de erro suportado pelo endpoint e pelo directoryUserId fornecido, conforme indicado acima. Um código não suportado, uma resposta malformada ou um estado HTTP inesperado constitui uma falha de integração e conduz à página de erro genérica. Em caso de falha técnica no conector, devolva o código de estado HTTP 500. Consulte Resolução de erros do navegador para encontrar os detalhes de diagnóstico através dos identificadores na 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, user_not_exists, user_disabled ou user_deleted 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, por qualquer motivo, um utilizador não tiver permissão para iniciar sessão através deste fluxo, valide primeiro o identificador de utilizador e a palavra-passe fornecidos. Só devolva uma rejeição baseada nesta restrição depois de verificar ambos com êxito, para que a restrição não revele se um identificador adivinhado pertence a um utilizador real. Devolva login_rejected de authentication, indique o motivo de diagnóstico em errorMessage e, opcionalmente, forneça orientações seguras ao utilizador em uiErrorMessage. Se não for possível verificar as credenciais, devolva a falha de autenticação habitual sem revelar a restrição.

O FoxIDs depende do conector para verificar as credenciais antes de devolver login_rejected; uma pesquisa de conta bem-sucedida ou o conhecimento de directoryUserId não são suficientes. Antes de as credenciais terem sido verificadas, apresente quaisquer instruções ou botões para métodos de início de sessão alternativos independentemente de o identificador fornecido corresponder a uma conta.

Utilize user_disabled e user_deleted apenas para comunicar o estado correspondente da conta no diretório. Estes códigos também desativam ou eliminam o utilizador interno e revogam o seu acesso; não são códigos genéricos de rejeição do início de sessão.

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.

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