# Company SSO (OpenID Connect) for the Department Portal and agents

RivetIT can accept sign-ins from one OpenID Connect provider at a time, for Department Portal logins and, optionally, for agents (staff). This supports compatible Authentik, Keycloak, and Ory Hydra installations using the authorization-code flow with PKCE. It does not provision people or change anyone's permissions. Microsoft Entra, passkeys, passwords and local two-factor remain available independently.

## Configure the provider

1. Create a confidential OpenID Connect client in the identity provider. Enable authorization code, PKCE S256, the `openid` scope, and either `client_secret_basic` or `client_secret_post` token authentication. Keep an RS256 or ES256 signing key available through JWKS and enable UserInfo. RivetIT does not use refresh tokens.
2. Add the **exact** redirect URI `https://YOUR-RIVETIT-HOST/client/login_oidc.php` to the provider allowlist. Use an exact match, not a wildcard. The host must match `config_base_url` in RivetIT's `config.php`.
3. Find the provider's exact issuer from its OpenID discovery document. Keep a trailing slash if the document includes one. For Authentik, use the per-application issuer (`https://auth.example/application/o/SLUG/`); its global issuer mode uses a different discovery path and is not supported here. For Keycloak, the issuer is normally `https://keycloak.example/realms/REALM`. For Ory Hydra, use its public issuer, not its admin API.
4. In **Administration → Settings → Identity provider**, enter issuer URL, client ID, and client secret. Enable company SSO and save. RivetIT verifies discovery and keeps the secret encrypted; leaving the secret field blank on a later save preserves it. Disabling the checkbox removes the sign-in button without changing account mappings.
5. In **Administration → Users → Department logins**, edit an existing Department login. Set **Sign-in method** to **OpenID Connect** and enter that user's immutable `sub` claim from the provider. Do not enter an email address unless the provider actually uses that string as its stable `sub`. The issuer and exact subject can map to only one RivetIT account. Existing local/Entra logins can be switched back; switching to local requires a new password. If you change the configured provider issuer, re-save each intended account mapping after verifying its subject at the new provider; old mappings do not transfer automatically.

**Optional: link on first sign-in by verified email.** In the identity provider settings, turn on *Link logins on first sign-in by verified email* (off by default). Then set a Department login to **OpenID Connect** and leave the subject blank. On that person's first sign-in RivetIT also requests the `email` scope and links the login only if the provider returns `email_verified: true` (the JSON boolean) and the email equals that login's email exactly, with exactly one eligible blank login matching. The issuer and subject are then stored and every later sign-in uses them alone, so a changed email never matters. A separate setting, *Require the provider to report the email as verified* (on by default), can be turned off for providers such as Authentik that report `email_verified: false` unless configured; only do that when just administrators can create users or edit email addresses at the provider. Logins that already have a subject, local/Entra/Odoo logins, disabled logins, unverified emails and ambiguous matches are never linked; the link is recorded in the audit log. Only enable this if the provider verifies every address and does not allow self-signup with arbitrary emails (Authentik's default scope mapping reports every email as verified).

The configured issuer, authorization, token, UserInfo, and JWKS endpoints must use HTTPS and the same host/port. RivetIT checks the discovery issuer exactly and validates the ID token signature, issuer, single configured client audience, authorized party when present, required numeric expiration and issued-at time, nonce, and UserInfo subject. A token with additional audiences is rejected because this integration has no configuration for trusting them. The browser transaction expires after five minutes. The token exchange uses a confidential client secret and PKCE; the secret never passes through the browser. An existing RivetIT session is replaced only after a complete successful sign-in.

## Agent sign-in with company SSO

Off by default. In **Administration → Settings → Identity provider**, turn on **Let agents sign in with company SSO**. The agent sign-in page then shows **Sign in with company SSO**. It uses the same provider and the same redirect URI as the Department Portal, so nothing new has to be registered at the provider.

- **Explicit link.** An agent can use it only after an administrator enters the agent's provider subject (`sub`) in **Administration → Users → edit user → Company SSO sign-in**. Email is never used to match an agent, and there is no first sign-in email linking for agents. The change is written to the audit log. A subject can be linked to one account only. This is separate from the Remote MCP identity fields.
- **Administrators are excluded.** An account with an administrator role cannot be linked and is refused even if a link is forced into the database, so a provider outage or mistake can never lock everyone out. Administrators sign in with a password or passkey.
- **Two-factor stays local.** The provider counts as the first factor only. An agent who has local two-factor still enters their authenticator code on the usual code step after the provider sign-in. There is no setting that skips it.
- **Credential vault stays locked.** No vault key is derived from an external identity, so after SSO the credential vault is locked and the credentials page says so; signing in with a password or a passkey unlocks it.
- **Which account.** The button used decides the account type, and the callback cannot change it: the agent button only matches agents, the Department Portal link only matches Department logins. The same person can have both links without any ambiguity.
- **Not offered** while a login key (Administration → Settings → Security) is required, because that key hides the sign-in page.
- Logging out ends the RivetIT session only; if the provider session is still active the person can sign in again immediately.

To turn it off for one agent, clear their subject; to turn it off for everyone, clear **Let agents sign in with company SSO**. Sign-in failures are logged with a specific, non-sensitive reason (for example `account_ineligible: no_agent_linked_to_this_subject`).

## Provider notes (tested)

Both sign-in kinds were exercised end to end, with real browser sign-ins, against **Authentik**, **Keycloak 26.8** and **Ory Hydra 2.3** (with a minimal login and consent app), plus a mock provider for the failure cases. Each needs the exact redirect URI `https://YOUR-RIVETIT-HOST/client/login_oidc.php`, the scopes `openid profile email` (only `openid profile` is requested unless email linking is on), authorization code with PKCE S256, and a signing algorithm of RS256 or ES256.

- **Authentik.** Use the per-application issuer (`https://auth.example/application/o/SLUG/`), a confidential client, and select an RSA signing key (the default HMAC signing is rejected). The `sub` is the hashed user ID unless you changed the provider's subject mode. Authentik reports `email_verified: false` unless a user attribute or scope mapping says otherwise; see the verified-email setting above.
- **Keycloak.** The issuer is `https://HOST/realms/REALM`. Create an OpenID Connect client with **Client authentication on** and **Standard flow** as the only flow, add the exact redirect URI, and under Advanced set **Proof Key for Code Exchange Code Challenge Method** to `S256`. The subject is the user's ID (a UUID, shown on the user's Details tab). Keycloak sends `email_verified` per user.
- **Ory Hydra.** Hydra has no user directory: you run a login and consent app that tells Hydra who signed in. The `sub` is whatever that app passes when it accepts the login request. If you use email linking, the app must also add `email` and `email_verified` to the ID-token session claims when it accepts consent. Register the client with `grant_types: [authorization_code]`, `response_types: [code]`, `scope: "openid profile email"`, `token_endpoint_auth_method: client_secret_basic`, and enforce PKCE (`oauth2.pkce.enforced: true`). Hydra's public URL must be the HTTPS issuer, because RivetIT requires every endpoint on the issuer's own host and port.

## Verify and recover

Use a test Department login with an explicit subject mapping. Start from the main RivetIT sign-in page, choose **Login with company SSO**, authenticate at the provider, and verify the Department Portal opens with that person's existing permissions. Also test an unmapped subject, a disabled login, and a second browser session: none should enter the portal. Provider failures return to the normal sign-in page with a generic message. Safe reason categories appear in the RivetIT login audit log; codes, tokens, and secrets are not logged by the application. Configure the reverse proxy to redact the `code` query parameter in access logs for `/client/login_oidc.php`.

To rotate a secret, create a new provider secret and save it in the identity-provider page. To disable SSO immediately, clear **Enable company SSO sign-in**. Existing RivetIT sessions remain active until they expire or sign out; this integration does not implement single logout. For rollback, disable the provider, set affected users back to local or Entra sign-in as appropriate, and set local passwords where needed. The schema migration adds disabled settings and nullable subject mappings; it does not change existing sign-ins.

The code path is based on the [OpenID Connect Core authorization-code flow](https://openid.net/specs/openid-connect-core-1_0.html), [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), and [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). See the provider's current setup guide: [Authentik OAuth2/OIDC provider](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/), [Keycloak server administration](https://www.keycloak.org/docs/latest/server_admin/), or [Ory Hydra documentation](https://www.ory.sh/docs/hydra/).
