Skip to content

LDAP and Microsoft Active Directory

JANUS can authenticate administrators and end users against an existing LDAP directory or a Microsoft Active Directory forest, while keeping JANUS authorization, multi-factor authentication, recovery and logging entirely inside JANUS.

This page is written for the administrator who has never read the source. It describes what an LDAP/AD provider definition is, where it lives, how a sign-in works, how directory groups become JANUS authority, how a stable identity is derived, what happens during an outage or a deprovisioning, and the rules JANUS will not let you break.

If you want the OpenID Connect equivalents, read External identity federation alongside this page: OIDC, LDAP and AD all converge on the same JANUS identity and authorization model.

Validation scope

Three things are deliberately kept separate and must not be read as one:

  • Implemented support for Microsoft Active Directory semantics (objectGUID durable identity, sAMAccountName, memberOf, primaryGroupID, nested groups) — implemented and covered by automated tests.
  • Compatibility evidence from a Samba AD DC — a real AD-protocol directory, used as compatibility evidence only. Samba AD is not Microsoft AD DS.
  • Real validation against a Microsoft Windows Server Active Directory Domain Services environment — deferred.

Real Microsoft Active Directory Domain Services interoperability has not yet been validated against a Microsoft Windows Server AD DS environment. The implementation has been validated using the available LDAP/OpenLDAP and Samba AD compatibility environments. Microsoft AD DS validation is deferred to a later manual acceptance campaign.

Until that campaign is run, treat the Microsoft-specific behaviours on this page as implemented-and-tested-by-construction rather than proven against a Microsoft host (for example multi-DC failover, Global Catalog, ranged retrieval, Microsoft lockout/expiry error codes and cross-domain/forest behaviour).

The one sentence that matters

Authenticating through LDAP or Active Directory grants no JANUS authority.

JANUS authorization is expressed only as bindings of a principal to a role at a scope, or as an explicit mapping from directory group to a role and scope. A successful bind, group membership, an e-mail address, a display name or a distinguished name never grant anything by themselves.

Where provider definitions live

An LDAP/AD provider definition is management state. It is stored in the controller's PostgreSQL database, administered through the Management API and the WebUI, and is not a Git desired-state object. That is deliberate:

  • administrative authentication configuration belongs with the rest of the administrative authentication state (principals, bindings, MFA policy), not with the network objects Git owns;
  • administering — and recovering from — a broken directory integration must not depend on Git being available;
  • the compiler and the reconciler do not know about provider definitions at all, so directory configuration can never reach a gateway or a data-plane object.

The bind credential value is never stored in that database. A provider carries a reference to it: an absolute path to a host-local file, or the name of an environment variable. JANUS never accepts, returns, logs or audits a bind password.

Generic LDAP versus Microsoft Active Directory

Both speak the same wire protocol, so both are one provider kind (ldap) with an explicit variant:

Variant Use it for Durable identity default
ldap OpenLDAP, 389 Directory Server, FreeIPA, NetIQ, any generic directory you must name a stable attribute (there is no universal one)
ad Microsoft Active Directory objectGUID (chosen automatically)

The variant also selects sensible attribute defaults. Choose ad for Active Directory so the correct durable object identity is used without extra thought.

Provider fields

All fields are optional unless marked required. Exactly one of the secret sources is used; a value is never accepted.

Identity and scope

Field Meaning
name required — the stable configuration key and the seed of the stable provider id. It must not change after creation. Lower-case letters, digits and -/_/.
variant ldap (default) or ad
displayName human-readable name; changing it never changes identity
deployment platform (default) or a deployment name / deployment:<uuid>
jitMode auto-create (default) or disabled; see Provisioning
enabled default true; a disabled provider refuses new directory logins
loginDomains the login-routing patterns this provider serves, e.g. ["corp.example"] or ["*.corp.example"]. Used by identifier-first sign-in (see Identifier-first sign-in). Optional; a provider with none is still reachable by an explicit provider selection through the API

Servers and transport

Field Meaning
servers required — one or more host or host:port entries, tried in order
port override the port for servers that do not name one (default 636 for ldaps, 389 otherwise)
transport required — ldaps (TLS from the first byte), starttls (TCP upgraded to TLS before any credential), or plain (cleartext)
tlsServerName the name verified against the server certificate when it differs from the connected host (for example an IP-addressed controller whose certificate carries a DNS name)
caFile absolute path to a PEM trust anchor; when empty the host system trust store is used
insecureSkipVerify dangerous — disable certificate verification. Never the default
allowPlaintext required for transport: plain; your explicit acknowledgement that the credential is sent in cleartext
connectTimeoutSeconds / operationTimeoutSeconds / totalTimeoutSeconds bounds (defaults 10 / 15 / 30)
Field Meaning
bindMode required — search (service bind + search + user bind) or direct (bind as the user with a DN template)
bindDn the service account DN (search), or the DN template with {login} (direct)
bindSecretFile / bindSecretEnv one of — where the bind password lives (a reference only)
allowAnonymousSearch permit an anonymous service bind; discouraged, and required if you configure no service account
userBaseDn required for search — where users are searched
userScope base, one or sub (default sub)
userFilter the user filter template. Must contain {login}; the substituted login is escaped as a filter value
loginAttributes alternative: equality matches over these attributes, OR-ed
userDnTemplate required for direct — a DN template with {login}

Stable identity

Field Meaning
stableIdAttribute the durable object-identity attribute. required for ldap; defaults to objectGUID for ad
stableIdNormalize guid renders a binary objectGUID canonically; otherwise the value is used verbatim
usernameAttribute / emailAttribute / displayNameAttribute mutable attributes copied as hints; never identity keys

Groups

Field Meaning
groupStrategy none (default), memberOf (read the user's own memberships), or search (search for groups referencing the user)
groupBaseDn / groupScope / groupFilter for search; groupFilter must contain {dn} or {subject}
groupIdAttribute the durable group identity (defaults to objectGUID for ad; required for ldap)
groupNameAttribute the mutable group display name (default cn)
groupMembershipAttribute the user attribute carrying direct memberships for memberOf (default memberOf)
nestedGroups none (default) or bounded (breadth-first, safely capped; requires search)
maxNestedDepth / maxGroups the nesting and count bounds (defaults 5 / 512)

Identifier-first sign-in

A human begins with a memorable login identifier — for example alice@example.com — and never with a distinguished name. The identifier is a login input, not an identity:

human login identifier  ("alice@example.com")
        |
        v   server-side discovery resolves the domain
eligible authentication context  (your deployment's directory)
        |
        v
eligible provider(s)  ->  a SAFE method label ("Active Directory")
        |
        v
directory credential  ->  stable external subject (objectGUID)  ->  JANUS principal/session

Two things are deliberately kept apart:

  • the human login identifier (alice@example.com, a UPN, an e-mail or a configured username) — used to discover/search the directory;
  • the durable external identity (provider id + stable external subject, i.e. the canonicalised objectGUID for AD) — what JANUS persists and links.

Changing alice@example.com to alice.smith@example.com therefore does not create a new JANUS identity: the stable directory subject is unchanged.

The tenant/deployment inventory is never disclosed. An unauthenticated caller is shown only a safe authentication-method label ("Active Directory", "LDAP directory", "Single sign-on"), never a provider name, a deployment name, a tenant, an id, or a count of unrelated customers. There is no organization selector and no anonymous endpoint that lists login deployments.

To make routing deterministic, give each directory provider the login domains it serves (loginDomains). JANUS refuses to save or enable two providers whose login domains overlap, so a domain can never resolve ambiguously and the choice is never resolved by configuration order. A domain that resolves to no provider (an unknown customer's domain, or a typo) is answered exactly like a bare username: it falls back to the local Janus account, disclosing nothing.

The same model applies to every external provider kind, including OpenID Connect: a provider that declares a login domain resolves to the safe label "Corporate SSO", and the flow is started from the identifier without the caller naming the provider. A provider with no login domain is not generically discoverable at all — it is reached only through an explicit deep link that names it (/login?sso=<provider>, or provider= on the API), which is not a catalogue because the caller must already know the name.

How a sign-in works

Which sequence runs is set by bindMode.

search (the recommended enterprise model):

  1. JANUS opens a trusted connection (LDAPS or StartTLS).
  2. It binds as the service account and searches userBaseDn for exactly one user matching userFilter with the login substituted (escaped).
  3. It derives the stable subject from stableIdAttribute.
  4. It opens a second connection and binds as that user to verify the presented password.
  5. It resolves the user's groups (bounded).
  6. The external identity and its groups flow into the same JANUS path OIDC uses: stable subject, JIT policy, explicit group mapping, MFA floor, JANUS session.

direct: JANUS binds as the user with a DN built from userDnTemplate (escaping the login), then reads the user's own entry over that connection to derive the stable subject and groups. It needs no service account, but requires that users may read their own entry.

Exactly one match, always

If the filter matches zero users the sign-in fails. If it matches more than one, the sign-in fails — JANUS never selects the first match, because that would be an authorization bug waiting to happen.

No filter injection

Your login text is never inserted into the filter as syntax. It is escaped as a filter value first, so a login of alice)(uid=* is treated as a literal username, not as a filter that matches everyone.

Stable identity

The durable identity is always

provider id + stable external subject

It is never the e-mail address, the username, the UPN text, the display name or the DN text.

Microsoft Active Directory

The durable identifier is objectGUID. JANUS renders it in the canonical 8-4-4-4-12 hexadecimal form, re-ordering the AD-stored byte order, so the same object produces the same subject from every domain controller.

  • Rename / move (a changed cn, sAMAccountName, userPrincipalName, mail or OU): the objectGUID is unchanged, so the identity is unchanged and any link and mapping keep working.
  • Delete / recreate: a new object gets a new objectGUID, so it is a new external identity even if the same username, UPN or e-mail is reused. The old link is retained for history but is inert.
  • Domain / forest: objectGUID is unique within a forest, but the provider is pinned to the servers you configure. Point one provider at one AD environment.

Generic LDAP

There is no universal immutable-ID attribute, so you must name one (entryUUID on OpenLDAP and 389 DS, ipaUniqueID on FreeIPA, a personnel number, …). If the attribute is missing on the matched entry, or is not unique, the sign-in fails closed — JANUS will not fall back to the DN.

Transport security

Use ldaps or starttls. With both, the credential is protected by TLS before it is sent.

  • Certificate verification is on by default. Prefer caFile (your internal CA in PEM form) over the system trust store when your directory uses a private CA.
  • tlsServerName lets you verify the certificate against a DNS name while connecting to an IP address.
  • insecureSkipVerify disables verification. It is dangerous, it is never the default, and a provider that uses it (or transport: plain) is reported as insecure everywhere: in the API, in the WebUI, and in the audit trail.
  • Plain LDAP (transport: plain) additionally requires allowPlaintext: true, so it can never be selected by accident. Use it only for a lab or an explicit compatibility case, and understand that the credential crosses the network in the clear.

Directory groups become authority only through an explicit mapping

Directory groups are inputs to explicit JANUS mappings, never authority by themselves:

directory group (provider, stable group identity)
        |
        |  an explicit ExternalGroupMapping row (management state)
        v
   (JANUS role, JANUS scope)          <- the existing RBAC vocabulary
  • An unmapped group grants nothing. Deny is the default.
  • A mapping targets a role and a scope, not a "JANUS group".
  • Mappings are keyed on the stable group identity (objectGUID / entryUUID), never the display name, so renaming a group changes nothing.
  • There is no pattern matching and no wildcard: one mapping is one explicit row.
  • Removing a mapping withdraws exactly the authority it granted, on the next authorization decision.

Nested groups

Nesting is explicit, never unbounded. Set nestedGroups: bounded (with groupStrategy: search) to expand parent groups breadth-first, up to maxNestedDepth and maxGroups. If the expansion would exceed a bound, the resolution fails closed rather than silently truncating. With the default (none) only direct memberships are reported, and nesting is an explicit non-feature.

Active Directory primary group. With groupStrategy: memberOf, AD does not list a user's primary group in memberOf. If primary-group membership matters, use groupStrategy: search (groupFilter: (member={dn})), which finds the primary group correctly.

Nested groups and bounds. A circular group structure is broken by a visited-set; depth and count bounds cap the work; the whole resolution stays inside the provider's operation and total timeouts.

Explicit identity linking

An external identity is linked to a JANUS principal by the immutable pair (provider, stable external subject):

  • JANUS never links or merges accounts because two usernames, UPNs or e-mail addresses match;
  • an administrator may link a directory subject to an existing principal, or unlink it, through the API or the WebUI;
  • linking a subject that is already linked to a different principal is refused as a conflict — never an automatic merge;
  • unlinking removes the link and retains the principal, its bindings and its history.

Provisioning (just-in-time)

jitMode decides whether a directory identity with no link may be provisioned:

Mode Behaviour
auto-create (default) the first directory login creates a JANUS principal. It receives no authority at all until an administrator grants a binding or a mapping applies
disabled an unlinked directory identity is refused with "this account is not provisioned for access". An administrator must create the principal and link it first

In both modes, authentication alone never makes anybody privileged.

Multi-factor authentication and recovery

The rules are identical to OIDC, because they are properties of the JANUS identity plane, not of the authentication mechanism:

  • A directory password does not satisfy the administrative MFA floor. Every human with effective authority at DeploymentAdministrator or above must satisfy a JANUS second factor. Bonding in through AD does not, and it does not count the directory's own MFA.
  • The directory is never the sole recovery root. Every independently administrable deployment keeps a qualifying local JANUS recovery authority (a local credential, an administrative binding, and a viable path to the MFA floor), and a change that would destroy the last one is refused.

See External identity federation for the full treatment of the MFA floor and Local Administrative Recovery Authority.

What JANUS does when the directory is unavailable

Situation Behaviour JANUS authority
Directory unreachable (DNS, TCP, TLS, bind, search, timeout) New directory logins are refused. Existing JANUS sessions keep working. Unchanged. Observed groups are never treated as absent.
Provider disabled or deleted New directory logins are refused. Unchanged. Existing JANUS sessions are not revoked: they are JANUS sessions.
A group was removed in the directory On the identity's next login the observed groups are refreshed and the mapping-derived authority disappears. Withdrawn automatically.
A principal is disabled in JANUS Its sessions are revoked immediately. Withdrawn.
A directory account is deleted, then recreated A new object has a new stable identity, so it is a new external identity. The old link is inert.
A user's password changes in the directory Nothing happens to an existing JANUS session; the next interactive login uses the new password. Unchanged. JANUS holds the session, not the password.
A user is disabled/locked in the directory The next login is refused. Unchanged for existing sessions.

An outage is not a deprovisioning. JANUS does not treat an unreachable directory as proof that an identity was removed, and it is not a directory synchronisation system: lifecycle changes take effect at the identity's next login, not by a background sweep. There is no LDAP/AD connector and no SCIM.

The deprovisioning cases, kept distinct

JANUS keeps these nine situations distinct, and none of them is conflated with another:

  1. outage — no authentication, no authority change;
  2. wrong credential — uniform sign-in failure;
  3. user deleted — next login is a new identity (new stable id);
  4. user disabled — next login refused;
  5. group removed — authority withdrawn on next login;
  6. provider disabled — new logins refused, sessions intact;
  7. provider deleted — new logins refused, sessions intact;
  8. delete/recreate — a new identity;
  9. JANUS principal disabled — sessions revoked immediately.

Diagnostics

An administrator authorized to administer the provider can run Test connection (WebUI) or POST /api/v1/auth/providers/{id}/test. JANUS performs a fresh, bounded, secret-safe probe and reports:

  • DNS resolution per server;
  • TCP reachability per server;
  • TLS handshake and the negotiated version;
  • the server certificate's subject, issuer and expiry, with a warning when it expires within 14 days;
  • the service bind result;
  • the validity of the user search base;
  • whether the stable-subject attribute is present on at least one user;
  • the validity of the group search base (when a group search is configured);
  • safe server metadata from the root DSE (vendor, supported versions, naming contexts);
  • latency per step.

Diagnostics never present a user credential and never read or return the bind secret. They require authority and obey scope, so a DeploymentAdministrator sees only their own deployment's providers.

Failure examples

Nobody can sign in through the directory. Sign-in fails with a uniform authentication failure. Run Test connection: the specific step that failed (DNS, TCP, TLS, certificate, service bind, user base, stable attribute) is reported. Existing JANUS sessions keep working, and every deployment administrator can still sign in with the local JANUS password.

A user is refused and you want to know why. Run Test connection, then check the audit trail. Common causes: the provider is disabled; the identity is not linked and jitMode is disabled; the userFilter does not match because the login attribute is wrong; the stable attribute is missing on that entry; the group filter is wrong, so a mapped group is not observed; the DN template does not match the naming layout.

"This account is not provisioned for access." jitMode is disabled and the directory identity has no link. Create the principal and link the identity, or switch the provider to auto-create.

Deleting a provider is refused. Links or group mappings still reference it. Unlink them and delete the mappings, or disable the provider instead — disabling has the same effect on new logins and keeps the history.

A user renamed in the directory can no longer see their devices. If the provider was configured with a generic stableIdAttribute that is not actually stable (for example uid), the rename produced a new identity. Re-link the principal; then fix the provider to use a genuinely durable attribute.

Security you should know

  • A compromised directory administrator controls group membership, and therefore can grant mapped roles. That is inherent in federation; the mitigations are that mappings are explicit, roles are a closed set, changes are audited, and JANUS MFA for administrators is still enforced.
  • Provider configuration is management state. Back it up with the database backup. The bind secret is a host-local file or environment variable and is the operator's responsibility to back up and rotate.
  • Rotating the bind secret. Replace the file or environment variable and restart the controller (or re-save the provider); JANUS never stores the value.
  • No directory synchronisation. There is no SCIM endpoint, no account provisioning and no password write-back. JANUS consumes directory identity; it is not a directory-management product.

API and WebUI

The LDAP/AD provider is administered through the same endpoints and pages as the OIDC provider:

Action API
List / create GET/POST /api/v1/auth/providers
Read / edit / delete / enable / disable / test /api/v1/auth/providers/{id}[/{action}]
Create / delete a group mapping POST /api/v1/external-group-mappings, DELETE /api/v1/external-group-mappings/{id}
Sign in (identifier-first, directory) POST /api/v1/auth/ldap/login with {"identifier": "alice@example.com", "password": "…"} — the server resolves the provider from the identifier
Discover a login context POST /api/v1/auth/discover with {"identifier": "alice@example.com"} — returns safe method labels only
Advertised providers GET /api/v1/auth/methods[?deployment=…]

A create/edit payload carries "kind": "ldap" and the fields above; a bind secret is named by bindSecretFile or bindSecretEnv, never sent as a value.

In the WebUI:

  • Platform administrators use External providers at /app/platform/identity-providers.
  • Deployment administrators use their own deployment's page at /app/deployments/<deployment>/identity-providers, where the deployment is taken from the page path and the scope selectors offer only that deployment.
  • The login screen is identifier-first: enter your login identifier (e.g. alice@example.com); JANUS resolves your authentication context server-side and shows a safe method label. The screen never lists providers, deployments or customers, and no organization/deployment selector appears before sign-in.

Reviewing a provider

A create/edit payload looks like this (AD example; the secret is a reference):

{
  "kind": "ldap",
  "name": "corp-ad",
  "variant": "ad",
  "displayName": "Corp Active Directory",
  "servers": ["dc1.corp.example", "dc2.corp.example"],
  "transport": "ldaps",
  "caFile": "/etc/janus/trust/corp-ca.pem",
  "bindMode": "search",
  "bindDn": "CN=janus-svc,OU=Service,DC=corp,DC=example",
  "bindSecretFile": "/etc/janus/secrets/corp-ad-bind",
  "userBaseDn": "DC=corp,DC=example",
  "userFilter": "(sAMAccountName={login})",
  "usernameAttribute": "sAMAccountName",
  "emailAttribute": "mail",
  "displayNameAttribute": "displayName",
  "groupStrategy": "search",
  "groupBaseDn": "DC=corp,DC=example",
  "groupFilter": "(member={dn})",
  "groupIdAttribute": "objectGUID",
  "groupNameAttribute": "cn",
  "loginDomains": ["corp.example"],
  "jitMode": "auto-create"
}

Limitations

  • No SAML, SCIM, Kerberos/SPNEGO browser SSO, NTLM, RADIUS, TACACS+ or PAM.
  • No password write-back, no directory account provisioning, no AD domain administration, no CA management.
  • No background synchronisation; lifecycle changes are observed at the next login.
  • memberOf and the AD primary group: see the note above; use search when the primary group matters.
  • The installer does not create an LDAP/AD provider; you add one through the API or the WebUI.