LDAP / Active Directory¶
Federate users from your LDAP or Active Directory directory — they authenticate against the directory and appear as managed HelixIAM users.
What it is¶
HelixIAM federates users against an LDAP or Active Directory directory. Users authenticate with their directory credentials and are federated into the realm, so your existing directory remains the source of truth while Helix provides modern SSO, MFA, and federation on top.
- Directory-backed authentication — credentials are validated against the directory at sign-in (direct bind; no redirect).
- Attribute mapping — map directory attributes onto Helix user attributes.
- On-demand sync — bring directory users into the realm and refresh them when you choose.
An LDAP directory is an identity provider with protocol: "ldap" (or "ad"). Its config holds the directory URL, the service (bind) account Helix uses to search, and the search base, filter, and attribute names that turn directory entries into Helix users.
Internal directories must be allowed by the deployment
The directory URL must be a single ldap:// or ldaps:// URL. A directory on a private or loopback address — the usual Active Directory setup — is refused until the deployment lists it in HELIX_FEDERATION_LDAP_ALLOWED_HOSTS (Helm: config.ldapAllowedHosts), as host names (ldap.corp, ldap.corp:636) or CIDR ranges (10.20.0.0/16); until then LDAP logins for the provider fail and the server logs the refusal. A realm admin cannot widen the list. The host is resolved once and both binds connect to that address; LDAPS verifies the certificate against the configured name; referrals are ignored; one bind sequence has a 15 s deadline.
Watch: federate users from an LDAP directory¶
In the console¶
LDAP and Active Directory connections have their own page, User federation (under Federation & eIDs). The Add identity provider wizard on Identity providers also offers LDAP / Active Directory and creates the same connection.
- Open User federation and click Add LDAP / AD.
- In the wizard, enter the Connection URL, the Bind DN of the service account Helix reads the directory with, and its Bind password. Continue through Mappers and Review, and create the connection.
- Open the connection. On the Connection tab you can change the URL, Bind DN and Bind password (write-only: leave it blank to keep the stored one; the tab shows whether one is set).
- On the Search & sync tab, set the User search base, User search filter (
{0}is the username), UID attribute, Email attribute, First-name attribute and Last-name attribute, and click Save changes. - Click Sync users under Sync users now to import or refresh the directory's users. Save your changes first.
Tip
LDAP and AD share the same wizard — the difference is only in the default attribute names (sAMAccountName/objectGUID for AD versus uid for OpenLDAP), which you set as part of the attribute mapping.
Over the API¶
An LDAP directory is created like any identity provider, with protocol: "ldap". The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.
Create an LDAP provider¶
# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)
curl -s -b cookies.txt \
-H "Content-Type: application/json" \
-H "X-XSRF-TOKEN: $CSRF" \
-d '{
"alias": "corp-ldap",
"protocol": "ldap",
"displayName": "Corporate Directory",
"enabled": true,
"config": {
"url": "ldaps://ad.corp.example:636",
"bindDn": "cn=helix,ou=service,dc=corp,dc=example",
"bindPassword": "…",
"userSearchBase": "ou=people,dc=corp,dc=example",
"userSearchFilter": "(uid={0})",
"uidAttribute": "uid",
"emailAttribute": "mail",
"firstNameAttribute": "givenName",
"lastNameAttribute": "sn"
}
}' \
"$HELIX_URL/admin/realms/$REALM/identity-providers"
{
"realmId": "acme",
"alias": "corp-ldap",
"protocol": "ldap",
"displayName": "Corporate Directory",
"enabled": true,
"config": {
"url": "ldaps://ad.corp.example:636",
"bindDn": "cn=helix,ou=service,dc=corp,dc=example",
"userSearchBase": "ou=people,dc=corp,dc=example",
"userSearchFilter": "(uid={0})",
"uidAttribute": "uid",
"emailAttribute": "mail",
"firstNameAttribute": "givenName",
"lastNameAttribute": "sn",
"bindPasswordSet": true
}
}
The bind password is write-only: the response reports bindPasswordSet instead of the value — see secrets are write-only. Leaving it out of an update keeps the stored password. The older names bindPw and bindCredential are still accepted on a write and are stored as bindPassword.
Config keys
url, bindDn, bindPassword, userSearchBase, userSearchFilter (defaults to (uid={0}); {0} is the username), uidAttribute (default uid), emailAttribute (default mail), firstNameAttribute (default givenName), lastNameAttribute (default sn).
Sync directory users¶
Run an on-demand synchronisation to import or refresh users — useful from a scheduled job or after a bulk change in the directory. The response reports how many entries synced and failed.
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
"$HELIX_URL/admin/realms/$REALM/user-federation/corp-ldap/sync"
Full endpoint set¶
Method & path (under /admin/realms/{realm}) |
Purpose |
|---|---|
GET /identity-providers · POST /identity-providers |
List / create providers |
GET · PUT · DELETE /identity-providers/{alias} |
Read / update / delete a provider |
POST /user-federation/{alias}/sync |
Import / refresh directory users |
See Identity providers for the shared flow, and the API reference for every field.
See also¶
- Identity providers — broker model and mappers
- OIDC & social brokers · SAML broker
- Users & credentials — how federated users are managed
- Authentication flows