OIDC single sign-on

What this page covers

Letting users in through the single sign-on the organization already has. One OIDC integration covers Azure AD, Okta, Google, and other providers that follow the specification, and several providers can run side by side. The login page shows a button for each enabled provider, redirects to none of them automatically, and keeps the local form in place.

What you need

• PUBLIC_BASE_URL in .env, from which the callback address is built. A provider without this value is marked as incompletely configured and stays off the login page.
• An application registered on the identity provider side, giving you the issuer, client ID, and client secret.
• At least one administrator account that signs in with a local password. Unsealing the master key accepts local administrator credentials only.

How to set it up

Directory and single sign-on now sit under External group mappings. Group claims are set in source details; role and user-group rules are on the external group mappings page. The old OIDC Providers address still opens; on Identity sources press Add provider:

1. Display name: the name on the login page button, for example Azure AD.
2. Issuer: has to be https. Fixed once created.
3. Client ID: fixed once created. One issuer and client ID pair holds one configuration.
4. Client secret: stored under envelope encryption; left empty on an update it keeps the existing value.
5. Additional scopes: openid is always sent, and profile and email can be added.

Microsoft Entra ID

For an issuer on login.microsoftonline.com, the settings page points to the tenant, client values, group claim name, and group value in the Entra interface. Configure the group claim in Token configuration; do not add groups scope for it. The page warns if that scope is present. If the Entra token lacks claims needed by verified-email or email-domain admission rules, those rules do not pass.

Admission modes

• Pre-bound accounts only: only accounts whose external identity was bound in advance can sign in.
• Automatic provisioning by rule: someone who matches the rules gets an account created at first login.

Provisioning rules combine the tenant identifier, the organization domain, the email domain, and a requirement that the email be verified. Rules of different kinds are joined with “and”, and several values of one kind with “or”. A rule that relies on the email domain alone is refused on a shared issuer, because that does not delimit an organization. A separate switch treats a provider as shared by several organizations, and it can only tighten the conditions.

Declare which issuers belong to your own organization with OIDC_DEDICATED_ISSUERS in .env.

Enabling and disabling

The enable switch takes effect immediately. On disabling, the interface warns that existing sessions and connections obtained through that provider stop working at once. A provider that already has identities bound to it is disabled rather than deleted.

What auditors can see

• A successful login leaves a record with the provider identifier and name, the authentication method, and which stage the login landed in (awaiting two-factor, awaiting binding, awaiting a password change, or holding a full session).
• The first login under automatic provisioning leaves an account creation record as well.
• A failed credential exchange is recorded as a failure; a login that fails the admission rules is recorded as a refusal, naming the rule that did not pass.
• A login from a source address outside the account’s allowed list is recorded as a refusal, with the basis for the decision.
• The authentication method and the provider are noted together, so single sign-on can be told apart from local logins in the existing audit views.