External identity federation (OpenID Connect)¶
JANUS can authenticate administrators and end users through an external OpenID Connect provider — Microsoft Entra ID, Keycloak, Okta or any standards-conformant issuer — while keeping JANUS authorization, recovery and MFA entirely inside JANUS.
Also available: JANUS can authenticate against an LDAP directory or Microsoft Active Directory through the same identity, authorization, MFA and recovery model. See LDAP and Microsoft Active Directory. Everything on this page about authorization, group mappings, JIT, MFA, recovery and outages applies equally to a directory provider.
This page is written for the administrator who has never read the source. It describes what a provider definition is, where it lives, how external groups become JANUS authority, what happens when the identity provider is unavailable, and the two rules JANUS will not let you break.
The one sentence that matters¶
Authenticating through an external provider 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 an external group to a role and scope. A successful login, provider membership, group membership, an e-mail address or IdP tenant membership never grant anything by themselves.
Where provider definitions live¶
A provider definition is management state. It is stored in the controller's PostgreSQL database, is 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 a provider — and recovering from a broken provider — must never depend on Git being available;
- the compiler does not know about provider definitions at all, so identity configuration can never reach a gateway.
The client secret value is never stored in that database. A provider carries a reference to the secret: an absolute path to a host-local file, or the name of an environment variable. JANUS never accepts, returns, logs or audits a client secret value.
Provider fields¶
| Field | Required | Meaning |
|---|---|---|
name |
yes | The stable configuration key, and the seed of the stable provider id. It must not change after creation: an external identity is linked to it. Lower-case letters, digits and -/_/. |
displayName |
no | Human-readable name. Changing it never changes identity resolution. |
issuer |
yes | The pinned issuer identifier, an absolute URL. It is compared against the discovery document and against every ID token. |
clientId |
yes | The OAuth client identifier. |
clientSecretFile |
one of | Absolute path to a host-local file holding the secret. The file must be owner-only (no group or other access), must not be a symlink and must not be replaceable by a non-owner. |
clientSecretEnv |
one of | Environment-variable name holding the secret. Use exactly one of the two. |
redirectUris |
yes | Exact-match allowlist. Wildcards are not supported. |
scopes |
no | Defaults to openid, profile, email. |
deployment |
no | platform (default) or a deployment name or deployment:<uuid>. |
jitMode |
no | auto-create (default) or disabled. See Provisioning. |
enabled |
no | Defaults to enabled. A disabled provider refuses new external logins. |
Additional options exist for non-default claim layouts: a group claim name, a
group-id field for providers whose group claim is an array of objects (Entra ID
uses id), and a signature-algorithm allowlist. The signature algorithm
allowlist never includes none or a symmetric algorithm.
The stable provider id¶
JANUS derives a provider's internal id deterministically from name. Two
consequences matter operationally:
- an identity link survives a redeployment, because the id does not change;
- renaming
displayNameis always safe, while changingnamewould produce a different provider and strand existing links.
Deployment scope¶
A provider is scoped either to the platform (offered to every deployment) or to one deployment.
A deployment-scoped provider:
- is reachable on the sign-in surface only through identifier-first discovery — the human enters a login identifier, Janus resolves its domain server-side, and only a safe method label ("Corporate SSO" for OIDC, "Active Directory" or "LDAP directory" for a directory) is shown. Providers are never listed on the generic sign-in page, so a deployment's provider cannot be discovered by an anonymous visitor;
- may be administered only by a caller authorized at that deployment (another deployment's administrator cannot see it, read it, disable it or test it — the API answers not found, so it cannot even learn that it exists);
- may only map external groups into its own deployment's scope.
That last rule is the isolation boundary: a provider belonging to Deployment A can never be used to create a mapping that grants authority over Deployment B.
The deployment-scoped operator page¶
Each deployment has its own External providers page in the WebUI:
A DeploymentAdministrator reaches their own deployment's page at
/app/deployments/<deployment>/identity-providers and can list, create, edit,
enable, disable, test, and delete providers for their own deployment, and
manage that deployment's group mappings — all without platform authority.
- The deployment is taken from the page's path and is authoritative, not a free-choice picker: the page offers only that deployment's scope, so an administrator cannot accidentally (or deliberately) create a provider in a foreign scope. The API re-checks the scope regardless of what the UI sends.
- A deployment page shows only that deployment's providers. Platform-scope providers are not disclosed there, and another deployment's providers are never shown — a request naming a deployment the caller is not authorized for is refused (as not found, so existence is not disclosed).
- Provider administration is its own authority (
provider:admin), granted at a scope. A DeploymentAdministrator holds it at their own deployment's scope only: administering a provider in another deployment, or a platform-scope provider, is refused (not found). - Provider administration is not principal administration. Holding it does
not grant authority over the principal plane — creating or editing
principals, roles, bindings, credentials or identity links still requires the
platform-scope
principal:adminauthority, exactly as before. - Provider administration is security-sensitive mutating control-plane
authority, so it is inside the mandatory administrative MFA floor: a
DeploymentAdministrator whose session has not satisfied a second factor is
refused
MFA_REQUIREDand must complete the enrolment/step-up ceremony first.
Platform-scope provider administration (a provider offered to every
deployment) remains a PlatformAdministrator capability, on the platform
External providers page at /app/platform/identity-providers.
External groups become authority only through an explicit mapping¶
External groups are inputs to explicit JANUS mappings, never authority by themselves:
external group (provider, immutable group subject)
|
| 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": JANUS has no separate RBAC group object, and adding one would create a second authorization system.
- Mappings are keyed on the immutable group subject, never on the group's display name, so renaming a group in the directory neither creates nor destroys JANUS authority.
- 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.
Group rename vs group replacement. Renaming a group changes only its display name; the mapping keeps working. Deleting a group and creating a new one with the same name produces a different subject and therefore a different mapping; the old mapping becomes inert.
Explicit identity linking¶
An external identity is linked to a JANUS principal by the immutable pair
(provider, external subject). The subject is the OIDC sub claim. E-mail is
data, never an identity key:
- JANUS never links or merges accounts because two e-mail addresses match;
- an administrator may link an external 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 — it is never an automatic merge;
- unlinking removes the link and retains the principal, its bindings and its audit history.
Provisioning (just-in-time)¶
jitMode decides whether an external identity that has no link yet may be
provisioned at all:
| Mode | Behaviour |
|---|---|
auto-create (default) |
The first external login creates a JANUS principal. It receives no authority at all until an administrator grants a binding or a mapping applies. |
disabled |
An unlinked external identity is refused. An administrator must create the principal and link the identity first. |
In both modes, authentication alone never makes anybody privileged.
What JANUS does and does not do when the provider is unavailable¶
| Situation | Behaviour | JANUS authority |
|---|---|---|
| Provider unreachable (network, DNS, TLS, key set) | New external logins are refused. Existing JANUS sessions keep working. | Unchanged. Observed group membership is not treated as absent. |
| Provider disabled or deleted | New external logins through it are refused. | Unchanged. Existing JANUS sessions are not revoked: they are JANUS sessions, not IdP tokens. |
| A group was removed at the provider | On the identity's next authentication 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. |
| External account deleted and recreated | A new account has a new sub, so it is a new identity. The old link is retained for history. |
Old link inert. |
JANUS does not treat an unreachable provider as proof that an identity was deprovisioned, and it is not a SCIM directory-synchronisation system: lifecycle changes take effect at the identity's next authentication, not by a background sweep.
Failure examples¶
The IdP is down and nobody can sign in externally. Sign-in through that provider fails with a uniform authentication failure. The WebUI shows the provider as not healthy under Test connection, with the specific reason (discovery unreachable, issuer mismatch, key set unreachable). JANUS authority is unchanged, and every deployment administrator can still sign in with the local JANUS password — see Local administrative recovery below.
A user is refused and you want to know why. Run Test connection for the
provider. Then check the audit trail for that provider's external-login
failures, and the principal's links. The most common causes are: the provider is
disabled; the identity is not linked and jitMode is disabled; the provider's
group claim does not carry the mapped group subject; the redirect URI registered
at the provider does not exactly match the allowlist.
A login is refused with "this account is not provisioned for access". The
provider's jitMode is disabled and the external identity has no link. Create
the principal and link the identity, or switch the provider to auto-create if
that is the intent.
Deleting a provider is refused. Identity links or group mappings still reference it. Unlink the identities and delete the mappings, or disable the provider instead: disabling has the same effect on new logins and retains the history.
Local administrative recovery¶
Every independently administrable deployment must retain at least one local JANUS administrator who can regain control when external identity is unavailable, broken, misconfigured, expired, deleted or compromised.
A qualifying local administrative recovery authority is a principal that:
- is active;
- is a human principal (never a service principal, never the break-glass principal);
- holds a local JANUS credential (so it signs in without any external provider);
- holds an administrative binding at platform scope or at that deployment's own deployment scope; and
- has a viable path to satisfy the mandatory administrative MFA floor — since MANDATORY MFA (below) applies to every administrator, a supposed recovery authority that could not complete compliant MFA-backed access would not be recovery at all. The controller always provisions MFA key material, so in practice this means the authority must complete the (always reachable) MFA enrolment ceremony before its recovery is fully assured.
JANUS refuses any change that would leave a scope without one. The refusal is enforced in the authoritative mutation, not in the WebUI, so the API, the WebUI and any future client receive the same protection. It applies to:
- deleting an administrative binding;
- disabling a principal;
- removing the final local credential or demoting the final administrator (any mutation whose effective result destroys the last qualifying path).
Every authoritative mutation that could change whether a principal qualifies — its active state, an administrative binding, a binding scope, or the existence or enabled state of a local credential — is either routed through this guard or does not exist as a mutation at all. There is deliberately no principal-delete operation and no local-credential removal operation; bindings can be created or deleted but never re-scoped.
An external (federated) administrator does not satisfy the invariant: a deployment whose only administrator signs in through the customer's IdP can lose administrative access when that IdP does. Host-local break-glass and bootstrap remain available as platform recovery, but they require operating-system access to the controller, which is exactly what the invariant exists to avoid requiring of an ordinary deployment administrator.
Reading the status. The WebUI External providers page shows the recovery readiness for the platform and for each deployment, in one of three states:
- Available — a qualifying authority holds a usable second factor, so compliant local recovery is possible now;
- Action required — a qualifying authority exists but must first complete MFA enrolment;
- Unavailable — no qualifying local administrative recovery authority exists.
The API exposes the same status at GET /api/v1/recovery-safety. JANUS never
reports Available when the only local administrator cannot currently complete
compliant administrative access.
Mandatory multi-factor authentication for administrators¶
Every human identity whose effective authority is administrative at DeploymentAdministrator level or above must satisfy a second factor.
This is a floor, not a setting:
- It applies to
deployment_adminandplatform_admin(and any future administrative role), at any deployment size. - It is derived from the principal's current effective grants, so changing a binding or an external-group mapping cannot lower it.
- A read-only administrator and a self-service user are not subject to the floor; the existing per-scope MFA policy is unchanged for them.
- A customer may require more (a per-scope policy), never less.
- A human administrator cannot disable the floor for themselves, because it is not a configuration value at all.
- External MFA assertions are not trusted. An
amr/acrclaim, or the fact that the provider is "enterprise", does not satisfy the floor. JANUS's own accepted factor does. - A service principal is not a human and is not forced through the floor: it authenticates with a scoped API token and holds exactly the authority its bindings grant.
- There is no "no key material" bypass. The floor is not conditional on the
MFA subsystem being configured or on any factor being enrolled yet. The
controller always provisions host-held MFA key material (a configured reference,
or a key generated on first start under the controller's state directory), so
the enrolment/recovery ceremony is always reachable. An administrator who has
not yet enrolled is restricted to that ceremony: every ordinary administrative
route answers
MFA_REQUIREDuntil a second factor is satisfied. JANUS never silently downgrades an administrative session to single-factor access, and it never dead-ends the administrator either.
Enrolling after an upgrade¶
An administrator upgrading from a build with no MFA enrolment signs in with their
usual primary factor and is then guided to set up a second factor: ordinary
administrative operations reply MFA_REQUIRED (not a bare 403), the account
page offers enrolment, and once a factor is confirmed the administrator's
session steps up and administrative operations resume. There is no interval in
which single-factor administration is allowed, and no permanent lockout.
Upgrading from a configuration-file provider¶
Before this milestone, OIDC providers were listed in the controller's
installation configuration (auth.oidc). On upgrade:
- every stored configuration entry that was marked
enabledis imported once into management state, keyed by its stable name; - the import is idempotent and non-destructive: a provider is inserted only when no provider with that stable name exists, so repeated starts never duplicate a provider and never overwrite an administrator's edit;
- from then on, management state is authoritative and the configuration file is no longer consulted for providers;
- a provider that is configured but unusable (an unreadable secret file, an incomplete definition) is still a startup error — JANUS fails closed rather than silently dropping a provider;
- a disabled configuration entry is not imported; configure it through the API or the WebUI if you want it.
Local-only installations are unaffected: no provider is required, local sign-in keeps working, and initial setup is never reopened.
Security limitations you should know¶
- A compromised or malicious IdP administrator can grant mapped roles. That is inherent in federation: whoever controls the group claim controls group membership. The mitigations are that mappings are explicit, roles are a closed set, every change is audited, and MFA for administrators is still enforced by JANUS.
- Provider configuration is management state. Back it up with the database backup; the secret values are host-local files or environment variables and are the operator's responsibility to back up.
- RP-initiated / single logout is not standardised here. Signing out of JANUS revokes the JANUS session; it does not end your session at the identity provider.
- No directory synchronisation. There is no SCIM endpoint and no directory-connector sweep; lifecycle changes are observed at the identity's next authentication. (An LDAP/Active Directory authentication provider is available — see LDAP and Microsoft Active Directory — but it is not a synchronisation system either.)
- A provider secret is symmetric material. Rotate it by replacing the file or environment variable and restarting the controller; JANUS never stores the value itself.