Guia para desenvolvedores

Active DirectoryLDAP / LDAPS

Autentique usuários contra Microsoft AD DS on-prem com o mesmo contrato JWT do login email/senha.

Visão geral

A API faz bind no controlador de domínio via LDAP ou LDAPS, valida credenciais, provisiona usuários locais automaticamente e retorna JWTs. Separado do Microsoft Entra ID (OAuth na nuvem) — focado em AD DS no DC.

Contrato da API

Use sAMAccountName ou userPrincipalName como username. A resposta é igual ao POST /auth/login.

LoginBind Active Directory
POST /api/v1/auth/ad/login
Content-Type: application/json

{
  "username": "jdoe",
  "password": "StrongP@ssw0rd123"
}

LDAP vs LDAPS

Configure AD_LDAP_URL com ldap:// ou ldaps://. Veja os guias de transporte para portas, firewall e TLS.

Guia LDAP →Guia LDAPS →

Modelo de usuário

O objectGUID do AD é salvo como activeDirectoryId. Email vem de mail ou userPrincipalName.

Roles a partir de grupos AD

Grupos de segurança atribuídos via AD / GPO aparecem no usuário como memberOf. Mapeie-os para roles da app com AD_LDAP_GROUP_ROLE_MAP (formato groupDnOrCn|role;…). Em cada login a API atualiza user.roles a partir desse mapa (desative com AD_LDAP_SYNC_ROLES_ON_LOGIN=false). Se nenhum grupo corresponder, usa-se AD_LDAP_DEFAULT_ROLES.

ExemploAD_LDAP_GROUP_ROLE_MAP
AD_LDAP_GROUP_ROLE_MAP=CN=Nest-Admins,OU=Groups,DC=example,DC=com|admin;Nest-Managers|manager;Nest-Users|user
AD_LDAP_DEFAULT_ROLES=user
AD_LDAP_SYNC_ROLES_ON_LOGIN=true