Developer guide

Active DirectoryLDAP / LDAPS

Authenticate users against on-prem Microsoft Active Directory Domain Services with the same JWT contract as email/password login.

Overview

The API binds to your domain controller over LDAP or LDAPS, verifies credentials, auto-provisions local users, and returns JWT access and refresh tokens. This is separate from Microsoft Entra ID (cloud OAuth) — it targets AD DS on your DC.

API contract

Use sAMAccountName or userPrincipalName as username. Response matches POST /auth/login.

LoginActive Directory bind
POST /api/v1/auth/ad/login
Content-Type: application/json

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

LDAP vs LDAPS

Set AD_LDAP_URL to ldap:// or ldaps://. See the transport-specific guides for ports, firewall, and TLS.

LDAP guide →LDAPS guide →

User model

AD objectGUID is stored as activeDirectoryId. Email comes from mail or userPrincipalName.

Roles from AD groups

Security groups assigned via AD / GPO appear on the user as memberOf. Map them to app roles with AD_LDAP_GROUP_ROLE_MAP (format groupDnOrCn|role;…). On each login the API refreshes user.roles from that map (disable with AD_LDAP_SYNC_ROLES_ON_LOGIN=false). If no group matches, AD_LDAP_DEFAULT_ROLES is used.

ExampleAD_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