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
(
objectGUIDdurable 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) |
Bind and user search¶
| 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 canonicalisedobjectGUIDfor 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):
- JANUS opens a trusted connection (LDAPS or StartTLS).
- It binds as the service account and searches
userBaseDnfor exactly one user matchinguserFilterwith the login substituted (escaped). - It derives the stable subject from
stableIdAttribute. - It opens a second connection and binds as that user to verify the presented password.
- It resolves the user's groups (bounded).
- 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
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,mailor OU): theobjectGUIDis 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:
objectGUIDis 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. tlsServerNamelets you verify the certificate against a DNS name while connecting to an IP address.insecureSkipVerifydisables verification. It is dangerous, it is never the default, and a provider that uses it (ortransport: plain) is reported as insecure everywhere: in the API, in the WebUI, and in the audit trail.- Plain LDAP (
transport: plain) additionally requiresallowPlaintext: 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 inmemberOf. If primary-group membership matters, usegroupStrategy: 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
DeploymentAdministratoror 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:
- outage — no authentication, no authority change;
- wrong credential — uniform sign-in failure;
- user deleted — next login is a new identity (new stable id);
- user disabled — next login refused;
- group removed — authority withdrawn on next login;
- provider disabled — new logins refused, sessions intact;
- provider deleted — new logins refused, sessions intact;
- delete/recreate — a new identity;
- 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.
memberOfand the AD primary group: see the note above; usesearchwhen the primary group matters.- The installer does not create an LDAP/AD provider; you add one through the API or the WebUI.