Skip to content

Docs / RivetIT / Integrations & sign-in

Company SSO with OpenID Connect

Sign in through Authentik, Keycloak or Ory Hydra using the authorization-code flow with PKCE.

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, OpenID Connect Discovery, and PKCE. See the provider's current setup guide: Authentik OAuth2/OIDC provider, Keycloak server administration, or Ory Hydra documentation.

This page is rendered from docs/OPENID_CONNECT_PORTAL.md in the RivetIT repository. View or edit on GitHub