Active Directory Directory Connector

O Active Directory Directory Connector e um componente FoxIDs que implementa a API Directory Connector para um dominio AD/LDAP.

Instale o componente dentro do ambiente Windows do cliente, onde possa alcancar os domain controllers. O FoxIDs chama o componente por HTTPS, e o componente valida utilizadores, altera passwords, define passwords e devolve propriedades e claims de utilizador a partir do Active Directory.

O Active Directory Directory Connector e instalado e configurado no servidor Windows/IIS proximo do Active Directory. No FoxIDs, o connector e depois ativado no ambiente FoxIDs em Settings > Environment > Directory connector settings, onde configura o connector API URL e o secret.

O componente e disponibilizado como zip Windows juntamente com as versões FoxIDs:

FoxIDs.DirectoryConnector.ActiveDirectory-{version}-win-x64.zip

Endpoints

O componente expoe:

GET /health
POST /authentication
POST /change-password
POST /set-password

O endpoint /health nao requer autenticacao e devolve apenas um estado minimo. Verifica a configuracao necessaria, AD bind, acesso de leitura a user search-base e acesso de leitura opcional a group search-base. Nao testa permissoes delegadas de set-password / password reset. Erros detalhados e stack traces sao registados no servidor e nao sao devolvidos pelo endpoint.

A resposta inclui apenas status, adBind, userSearch e groupSearch. status e ok quando a configuracao necessaria e valida, o AD bind tem sucesso, o acesso a user search-base tem sucesso e o acesso a group search-base nao falhou. groupSearch e not_configured quando nao existe group search base configurada. Se uma verificacao nao puder ser executada porque uma verificacao anterior falhou ou falta configuracao, o campo e devolvido como unknown.

Requisitos

Windows Server com IIS.
ASP.NET Core Hosting Bundle para .NET 10.
Acesso de rede do servidor IIS ao domain controller configurado.
LDAPS ou outro canal seguro para operacoes de password.
Um dominio AD por deployment do connector.
Uma domain service account se forem usadas credenciais configuradas.
Permissao delegada de AD password reset se set-password tiver de ser suportado.

Uma configuracao recomendada e um servidor IIS domain-joined a executar o application pool como uma domain service account. Bind credentials configuradas atraves de appsettings.json ou environment variables tambem sao suportadas.

Autenticação

Configure uma API key forte em appsettings.json.

O FoxIDs envia autenticacao HTTP Basic com API ID directory_connector e o secret configurado.

Use o header X-FoxIDs-Api-Key: <api-key> apenas se um reverse proxy em frente do Directory Connector tratar a autenticacao Basic antes de o pedido chegar ao componente e reescrever o api-key.

Pesquisa e associação AD

O componente pesquisa primeiro no AD com a identidade de servico configurada. Suporta lookup por:

email
phone
username
directoryUserId quando o FoxIDs ja o conhece

O utilizador e identificado no FoxIDs com o objectGUID do AD codificado em base64. Este valor e devolvido como directoryUserId e mantem-se estavel se email, phone ou username mudarem.

Para autenticacao por password, o componente encontra o distinguished name do utilizador e depois faz bind ao AD como esse utilizador com a password submetida. Isto evita ambiguidades na pesquisa do utilizador e suporta todos os tipos de identificador configurados.

Para password change, o AD valida a password atual e a password policy.

Se a password policy do FoxIDs estiver ativada para o Directory Connector, o FoxIDs pre-valida o comprimento, a complexidade e o historico da password antes de chamar o connector. Isto da ao utilizador feedback mais preciso para estas verificacoes. O AD continua autoritativo e ainda pode rejeitar a password posteriormente com password_not_accepted, por exemplo devido ao comprimento minimo, complexidade, historico de password, minimum password age, fine-grained password policy ou custom password filter.

Para set-password, a identidade de servico configurada tem de ter direitos delegados de reset-password.

Acesso da conta de serviço AD

O connector deve correr com uma identidade de servico AD dedicada. Nao torne esta identidade num domain administrator. Use um utilizador normal de dominio, ou um custom security group que contenha o utilizador do connector, e delegue apenas as permissoes necessarias nas OUs usadas pelo connector.

Para user lookup e authentication, a identidade do connector deve ter permissao para pesquisar em cada OU configurada em UserSearchBases e ler os objetos de utilizador e atributos usados pelo connector. Uma nova identidade de servico AD dedicada muitas vezes ja tem este acesso de leitura por predefinicao, a menos que as ACLs do AD tenham sido restringidas.

Para password authentication, o connector primeiro encontra o utilizador com a identidade de servico e depois faz bind ao AD como utilizador com a password submetida. Isto nao requer que a identidade de servico conheca ou reponha a password do utilizador.

Para password change, quando o utilizador fornece a password atual, o connector usa o comportamento de password change do AD e o AD valida a password atual e a password policy.

Para set-password / password reset, delegue direitos de password reset nos user objects em cada OU configurada em UserSearchBases onde o connector deve suportar password reset. Em Active Directory Users and Computers, clique com o botão direito na user OU usada pelo connector, selecione Delegate Control..., selecione a identidade do connector e, no passo Tasks to Delegate, selecione Reset user passwords and force password change at next logon.

Delegar a permissão Reset user passwords and force password change at next logon à identidade do connector

Delegue também quaisquer permissões adicionais relacionadas com password exigidas pela domain policy, apenas se o ambiente usar essas operações. Para group role claims, conceda a identidade do connector acesso de leitura nos GroupSearchBases configurados. Deve conseguir listar a group OU e ler atributos de grupo como cn, distinguishedName e member.

Configuração

A configuracao usa a configuracao standard .NET. Os valores podem ser definidos em appsettings.json, environment variables, configuracao IIS ou outro provider de configuracao .NET.

Exemplo:

{
  "DirectoryConnector": {
    "ApiKey": "change-me",
    "ActiveDirectory": {
      "Domain": "example.local",
      "Server": "dc01.example.local",
      "Port": 636,
      "UseSsl": true,
      "Bind": {
        "Mode": "Integrated",
        "Username": "",
        "Password": ""
      },
      "UserSearchBases": [
        "OU=Users,DC=example,DC=local"
      ],
      "GroupSearchBases": [
        "OU=Groups,DC=example,DC=local"
      ],
      "UserIdentifiers": {
        "Username": "sAMAccountName",
        "Email": "mail",
        "Phone": "telephoneNumber"
      },
      "Claims": [
        {
          "Claim": "name",
          "Attribute": "displayName"
        },
        {
          "Claim": "given_name",
          "Attribute": "givenName"
        },
        {
          "Claim": "family_name",
          "Attribute": "sn"
        }
      ],
      "GroupClaims": [
        {
          "Claim": "role",
          "GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
          "IncludeNestedGroups": true,
          "Value": "employees"
        }
      ]
    }
  }
}

DirectoryUserId e sempre mapeado a partir do objectGUID do AD e devolvido codificado em base64. Nao e configuravel.

UserIdentifiers controla quais atributos AD podem ser usados para lookup por email, phone e username e devolvidos como identificadores de utilizador de topo. Pelo menos um de Email, Phone ou Username tem de estar configurado e ser devolvido pelo AD para uma resposta valida do connector. Remova um mapping de identifier se esse campo nao deve ser usado para lookup ou devolvido ao nivel principal. O mesmo atributo AD ainda pode ser configurado como claim em Claims.

Definicoes importantes:

ApiKey: Shared secret usado pelo FoxIDs para autenticar no connector. O FoxIDs envia-o como autenticacao HTTP Basic com API ID directory_connector. Use um valor forte e unico e, sempre que possivel, guarde-o como environment variable ou definicao IIS.
ActiveDirectory:Domain: Nome do dominio AD usado ao ligar ao dominio, por exemplo example.local.
ActiveDirectory:Server: Domain controller ou endpoint LDAP opcional. Se omitido, o connector usa Domain.
ActiveDirectory:Port: Porta LDAP. Use 636 para LDAPS.
ActiveDirectory:UseSsl: Ativa LDAPS. Mantenha-o ativado para operacoes de password, a menos que outro canal seguro esteja garantido.
ActiveDirectory:Bind:Mode: Integrated usa a identidade do IIS application pool ou a identidade do processo. ConfiguredCredentials usa o Username e a Password configurados.
ActiveDirectory:Bind:Username and ActiveDirectory:Bind:Password: Credenciais usadas apenas quando Mode e ConfiguredCredentials. Prefira environment variables ou configuracao IIS para a password.
ActiveDirectory:UserSearchBases: Um ou mais distinguished names onde os utilizadores sao pesquisados, por exemplo OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases: Um ou mais distinguished names onde os grupos de role configurados sao pesquisados.
ActiveDirectory:UserIdentifiers: Atributos AD opcionais usados para lookup e identificadores de utilizador de topo: Email, Phone e Username. Configure pelo menos um.
ActiveDirectory:Claims: Atributos de utilizador devolvidos como claims para o FoxIDs, por exemplo name, given_name, family_name ou email.
ActiveDirectory:GroupClaims: Memberships de grupos AD devolvidas como claims, tipicamente claims role. Veja Claims de grupo para detalhes de configuracao.

Claims de grupo

Os group claims estao desativados por predefinicao. Para os ativar, adicione uma ou mais entradas a ActiveDirectory:GroupClaims.

Cada entrada GroupClaims define o tipo de claim a devolver e quais memberships de grupos AD devem produzir esse claim. Claim e obrigatorio e e tipicamente role.

Existem tres configuracoes comuns:

"GroupClaims": [
  {
    "Claim": "role",
    "IncludeNestedGroups": true,
    "ValueAttribute": "cn"
  },
  {
    "Claim": "role",
    "GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
    "IncludeNestedGroups": true,
    "Value": "employees"
  },
  {
    "Claim": "role",
    "GroupName": "Administrators",
    "IncludeNestedGroups": true,
    "ValueAttribute": "cn"
  }
]

Se nem GroupDistinguishedName nem GroupName estiver configurado, o connector pesquisa nos GroupSearchBases configurados e devolve um claim por cada grupo correspondente do qual o utilizador e membro. Neste modo, nao configure Value; o valor do claim deve vir de ValueAttribute. Com o ValueAttribute predefinido em cn, um grupo com o nome admin_access devolve:

{ "type": "role", "value": "admin_access" }

Use GroupDistinguishedName quando souber o DN exato do grupo AD. Isto evita uma pesquisa por nome e e a opcao mais precisa.

Use GroupName quando o connector tiver de encontrar um unico grupo com base no respetivo valor cn em GroupSearchBases. A pesquisa tem de corresponder exatamente a um grupo. Se existir mais de um grupo com o mesmo cn nos GroupSearchBases configurados, o pedido falha porque o mapeamento do grupo e ambiguo.

Use Value apenas quando GroupDistinguishedName ou GroupName estiver configurado e o claim devolvido tiver de ter um valor fixo independente do nome do grupo AD. Por exemplo, um grupo com DN CN=Employees,OU=Groups,DC=example,DC=local pode devolver o valor role employees.

Se Value nao estiver definido, o connector le o ValueAttribute configurado do grupo AD correspondente. O ValueAttribute predefinido e cn, o que devolve o nome do grupo AD como valor do claim. Configure outro atributo de grupo apenas se esse atributo existir no objeto de grupo e contiver o valor que deve ser enviado para o FoxIDs.

IncludeNestedGroups controla como a membership e verificada:

true usa a regra de correspondencia recursiva do AD, pelo que o claim e devolvido se o utilizador for membro direto ou atraves de grupos nested.
false verifica apenas a membership direta no grupo correspondente.

Instalação no IIS

O componente e distribuido com Xcopy. Nao tem base de dados nem installer; atualizar ou fazer rollback faz-se substituindo os ficheiros na pasta do website IIS, mantendo a configuracao especifica do ambiente.

Instale o ASP.NET Core Hosting Bundle for .NET 10 (direct download) no servidor Windows.
Crie uma pasta para o componente, por exemplo C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Extraia o zip da release para a pasta.
Configure appsettings.json ou environment variables.
Crie um IIS application pool.
Defina a identidade do app pool para uma domain service account, ou configure bind credentials em appsettings.json.
Crie um site ou application IIS a apontar para a pasta extraida.
Associe o site a HTTPS.
Crie a pasta de logs C:\inetpub\logs\LogFiles\foxids-ad e conceda acesso de escrita a identidade do application pool. Por exemplo, se o application pool do IIS se chamar FoxIDs.DirectoryConnector.AD, conceda acesso de escrita a IIS AppPool\FoxIDs.DirectoryConnector.AD.
Verifique GET /health.

Para um FoxIDs API URL, use o connector base URL, por exemplo:

https://connector.example.com

O FoxIDs acrescenta authentication, change-password e set-password a esse base URL.

Certificado TLS

O FoxIDs chama o connector por HTTPS, por isso o site IIS deve ter um certificado TLS trusted. Pode usar o seu proprio certificado ou, opcionalmente, criar um certificado gratuito Let's Encrypt com win-acme.

Com o win-acme, descarregue a ultima release win-acme.v2.x.x.x64.pluggable.zip, extraia-a para uma pasta permanente, execute wacs.exe a partir de um Command Prompt elevado e selecione o site IIS que aloja o Directory Connector. O win-acme adiciona o binding HTTPS e regista a renovacao automatica do certificado no Windows Task Scheduler.

Veja a FoxIDs Windows / IIS HTTP and HTTPS guide para o fluxo completo do win-acme.

Configuração do ambiente FoxIDs

Depois de o connector estar instalado e acessivel por HTTPS, ative-o no ambiente FoxIDs:

Abra o FoxIDs Control Client.
Selecione o tenant e o ambiente que deve usar o connector.
Va a Settings > Environment.
Encontre Directory connector settings.
Ative o directory connector.
Introduza o connector API URL, por exemplo https://connector.example.com.
Introduza o mesmo secret que o ApiKey do connector.
Escolha se o FoxIDs deve guardar uma copia local da password e se a password policy do FoxIDs deve ser aplicada antes de chamar o connector.

Quando a password policy do FoxIDs esta ativada, o FoxIDs valida o comprimento, a complexidade e o historico da password antes de chamar o connector. Isto da aos utilizadores feedback imediato da policy do FoxIDs, mas o AD continua autoritativo e ainda pode rejeitar uma password com password_not_accepted devido ao comprimento minimo, complexidade, historico de password, minimum password age, fine-grained password policy ou custom password filter.

Definições do FoxIDs Directory Connector para Active Directory

O API URL no FoxIDs tem de apontar para o base URL do connector. O FoxIDs acrescenta os nomes dos endpoints quando chama o connector.

Por predefinição, em Login authentication method só está ativado o login com endereço de email. Se os utilizadores puderem iniciar sessão com username ou número de telefone, ative os user identifiers correspondentes em Login authentication method.

O exemplo abaixo tem username e email ativados.

User identifiers de FoxIDs Login authentication method para Directory Connector

Patching e atualizações

Descarregue a nova release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip e reveja as release notes.
Extraia o zip para uma pasta temporaria e copie os ficheiros atuais appsettings*.json, ou mantenha os secrets nas IIS environment variables.
Pare o site IIS ou o application pool.
Renomeie ou copie a pasta atual para uma pasta de backup, por exemplo C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Faca Xcopy dos novos ficheiros para C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory e verifique as permissoes NTFS da identidade do app pool.
Inicie o application pool e verifique GET /health, depois teste um login do Directory Connector ou uma operacao de password.
Se for necessario rollback, pare o app pool, restaure a pasta de backup para o path live e inicie novamente o app pool.

O web.config predefinido escreve logs ASP.NET Core stdout em C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Mantenha o stdout logging ativado ate o connector ser verificado e considere desativa-lo ou encaminhar os logs para o sistema normal de logs do ambiente apos validacao em producao.