Single sign-on with OIDC
Facet signs accounts in through external identity providers with OpenID Connect (OIDC). The server starts an authorization-code flow, verifies the provider’s identity token, and signs the account in. You configure each provider as a document, so every change is audited and reversible.
When to use this
Section titled “When to use this”- Your organization runs an identity provider and members must sign in with their work accounts.
- You must decide whether unknown members get an account automatically.
- You must stop password sign-in and allow the provider only.
Before you start
Section titled “Before you start”- The right. You need
createandupdaterights oniam.OIDCProvider. The seededadminrole holds them; theeditorrole has the doctype carved out of its grants. - Provider details. Gather from your provider: the issuer URL, the client id, and the client secret.
- The redirect address. Set it at your provider to
https://<your-host>/auth/oidc/<name>/callback.
1. Create the provider document
Section titled “1. Create the provider document”Open Configure → Platform → OIDC and select New. Fill the fields:
| Field | Holds | Rules |
|---|---|---|
name |
The URL segment in /auth/oidc/{name} |
Lowercase letters, digits, hyphens. Immutable after create. |
label |
The text on the sign-in button | Defaults to the name. |
issuer |
The provider’s issuer URL | Must be an absolute https URL. Plain http is accepted only on a loopback host, for a development mock provider. |
client_id |
The OIDC client id at the provider | From your provider’s client registration. |
client_secret |
The confidential-client secret | Stored in the secret store. The form stages it out-of-band; documents carry only a marker. Never shown again. |
domains |
Email-domain allowlist | Lowercase entries, for example example.tld. Empty means link-based sign-in only. |
auto_provision |
Create accounts for unknown people | When true, default_role is required. |
default_role |
The role for provisioned accounts | Applied at creation only. |
scopes |
The OIDC scopes to request | Defaults to openid, email, profile. |
enabled |
The per-provider switch | Disabled providers deny like unknown names. |
You can also create the provider through the document API:
curl -k -X POST -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "corp-idp", "label": "Company sign-in", "issuer": "https://idp.example.tld", "client_id": "facet-prod", "domains": ["example.tld"], "auto_provision": false, "enabled": true }' \ "https://facet.localhost:3443/Api/iam/OIDCProvider"The create hook validates the fields and answers 422 on a bad value. The
client secret rides a separate stage call, never the document body.
2. Check the sign-in page
Section titled “2. Check the sign-in page”Open the login page in a private window. Under the password form, Facet shows one Continue with button per enabled provider. The button list comes from a public read:
curl "https://facet.localhost:3443/Api/iam/oidc/providers"The answer carries the authentication mode and the display names only. The issuer, the client id, and the secret never leave the server.
3. Decide who gets an account
Section titled “3. Decide who gets an account”Two paths bring an unknown person in:
-
Linking. The provider returns a verified email whose domain is in the allowlist, and an account with that email exists. Facet links the identity to that account and signs them in. The join key is the pair of provider name and provider-side subject, never the email, so an email change at the provider cannot take an account over.
-
Just-in-time provisioning (JIT). The identity is unknown, the email is verified and allowlisted, and
auto_provisionis on. Facet creates the account with the provider’sdefault_roleand signs the person in. The link is stored on the account’sfederated_identitiesarray.Service accounts never federate. A suspended or disabled account denies; the reason stays in the audit log.
The local MFA check does not apply on this path. The provider is the factor of record; see Enforcing MFA for the password path.
4. Read the audit trail
Section titled “4. Read the audit trail”Three events land in the login-event log:
| Event | Written when |
|---|---|
oidc_provisioned |
Facet created an account through JIT. |
oidc_login |
An OIDC sign-in issued a session. |
oidc_denied |
Any denial. The details carry the machine-readable reason. |
See Auditing activity for how to read the log. The browser always sees one generic error; the reason never reaches it.
5. Require single sign-on
Section titled “5. Require single sign-on”Open Configure → Platform → Settings, Security chapter, and set Authentication mode. The two modes:
| Mode | Behaviour |
|---|---|
hybrid (default) |
Password sign-in and provider sign-in both work. |
oidc_only |
The password route refuses with 403 and writes a password_login_denied event. The password reset and the first-credential bootstrap refuse with 422. The login page hides the password form and the reset link. |
The write gate refuses a save that sets oidc_only while no enabled provider
exists, so one save cannot lock every sign-in path out.
6. Recover from a lockout
Section titled “6. Recover from a lockout”When the only enabled provider is dead and no session survives, run on the server host:
facet auth:mode hybridThe command sets the mode on the settings document through the normal write path. The policy gates read the document row directly, so every running server applies the mode at once, without a restart.
Troubleshooting
Section titled “Troubleshooting”The sign-in returns to the login page with a generic error
Section titled “The sign-in returns to the login page with a generic error”The audit log holds the reason under oidc_denied. Common causes: a wrong
client secret, a wrong issuer, a redirect address that does not match, or a
disabled provider.
A person cannot sign in and no error shows
Section titled “A person cannot sign in and no error shows”Check their account status. A suspended or disabled account denies on every path.
A new member gets no account
Section titled “A new member gets no account”JIT needs all four conditions:
- An unknown identity.
- A verified email.
- An allowlisted domain.
auto_provisionon.
Check the provider document.
The settings write refuses oidc_only with 422
Section titled “The settings write refuses oidc_only with 422”No enabled provider exists. Enable or create one first.
The provider button does not show
Section titled “The provider button does not show”The provider is disabled, or the login page failed to read the public provider
list. Check GET /Api/iam/oidc/providers.
Related
Section titled “Related”- Sign in, MFA, reset your password — the sign-in steps from the account holder’s side.
- Manage accounts — the
federated_identitiesfield on the account. - Assigning roles and role election — the role a provisioned account gets.
- Enforcing MFA — why the MFA gate does not apply on this path.
- Auditing activity — the login-event log.
- Internals on GitHub: oidc.md.