Skip to content

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.

In the console

  1. Open Federation & eIDs → Identity providers and click Add identity provider.
  2. Choose the LDAP / Active Directory directory type.
  3. Provide the directory connection URL and the bind account Helix uses to read it.
  4. Set the search base, user search filter, and attribute mapping that define which directory entries become Helix users and how their fields map.
  5. Save, then Sync users on demand to populate or refresh the realm from the directory. The federation provider is loaded at runtime and authenticates matching users against the directory.

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,
    "bindPwSet": false,
    "bindCredentialSet": false
  }
}

The bind password is write-only: the response reports bindPasswordSet (and the flags of its alternative names bindPw / bindCredential) instead of the value — see secrets are write-only.

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"

{ "synced": 128, "failed": 0, "errors": [] }

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