OpenID Connect

Platrium can hand sign-in over to any OpenID Connect provider. There is no "Auth0 integration" and no "Okta integration": an administrator gives Platrium an issuer URL, a client ID and a client secret, and discovery does the rest. If it speaks OIDC, it works!

The Big Idea: Protocols Only Verify

Local passwords, OIDC and (in the enterprise edition) SAML all do the same job in the end: prove who someone is. Everything after that is identical, so it lives in one place.

A protocol turns its own response (an ID token, a SAML assertion) into an IdpAuthHandoff: a subject, an email, a name. It does not decide whether the person is allowed in. That is the job of Admit and the Manager:

• IdpProvider.Admit is the one gate every sign-in passes. It refuses a disabled provider, a disabled user, and an email outside the provider's allowed domains.
• Manager.HandleFederatedLogin finds the user, creates them on first sign-in if the provider allows it, keeps their name and email current, and starts the session.

The OIDC handler never asks "is this provider enabled?" It only knows how to do OIDC.

How A Sign-In Works

The pieces worth knowing:

• Discovery finds every endpoint from the issuer URL, so nothing about a provider is hardcoded.
• PKCE (S256) is always on, even though we also use a client secret.
• The ID token is checked for signature, issuer, audience, expiry and the nonce. If the email is not in the token, we ask the userinfo endpoint, but only trust it for the same subject.
• return_to is cut down to a same-origin path (and at most 512 characters), so a sign-in link can't bounce you to someone else's site.

Where A Sign-In In Progress Lives

Between leaving for the provider and coming back, Platrium has to remember the state, nonce and PKCE verifier. It remembers them in the browser, in a short-lived cookie that only the server can read.

The value is sealed (encrypted and authenticated) with a key derived from PLATRIUM_SECRET_KEY. Each sign-in gets its own cookie, named platrium_authverify_ plus a short hash of its state. It is HttpOnly, SameSite=Lax, good for ten minutes, only sent to the callback path, and removed by the callback whatever happens.

Who Gets An Account

Identity is the pair (provider, subject): the provider's own stable ID for the person (OIDC's sub), never their email.

Each external provider carries a provisioning policy, the same for every protocol:

On every sign-in the user's email and display name are refreshed from the provider, which is the source of truth for who they are. Their external_id never changes.

Redirect URIs

Every provider is registered with its own callback address:

{APP_URL}/api/auth/oidc/{idpId}/callback

APP_URL is the public address of the installation (for example https://files.example.com). The provider's ID in the path means a callback says which provider, and therefore which tenant, answered before anything else is looked at. With several tenants and several providers each, a single shared callback would have nothing to go on.

The admin API returns the finished address as a read-only redirectUri, and the settings page shows it with a copy button.

Storing A Provider

A provider is two rows. idp_providers holds what every provider has (name, type, enabled, the provisioning policy). idp_oidc_configs holds the OIDC settings, one row per provider, with typed columns:

A later SAML provider gets its own table beside this one, so each protocol has typed, required columns instead of a blob of JSON.

The Secret Key

PLATRIUM_SECRET_KEY is required: the engine will not start without it. It must be the same on every instance of a cluster. Different purposes (signing upload receipts, sealing client secrets, sealing sign-in cookies) get their own keys derived from it, so none shares raw key bytes with another.

The Built-In Provider Is Special

Every tenant gets one LOCAL provider when it is created. It is the fallback that keeps people signed in when SSO is down, so it is read-only and permanent: it cannot be created again, edited, disabled or deleted. That rule is in IdpStore and nowhere else, so every caller gets the same answer.

Managing Providers

Administrators (anyone holding idp.manage, which is the super administrator today) use the Identity providers page in the admin console, backed by these GraphQL fields:

The settings every provider shares are one form, whatever the type. Only the connection settings differ, and the web app takes them from a small registry (connections/index.ts), so adding SAML later is one new entry.

Trying It With Auth0

Auth0 is a handy way to try this without running your own provider.

export APP_URL=http://localhost:3000
export PLATRIUM_SECRET_KEY="$(openssl rand -base64 32)"

When Something Goes Wrong

A failed sign-in sends the person back to the login page with ?error=<code>, and the page shows a plain sentence. The detail goes to the engine log, never to the browser.

For sso_expired, look for the log line starting with oidc callback. It says exactly why: no cookie, a cookie from another sign-in, the wrong provider, or too slow.

Not Yet

• Logout. Signing out of Platrium does not sign you out of the provider, and a provider's logout notice does not end Platrium sessions. (sessions_valid_after is already there for the second.)
• Disabling doesn't sign anyone out. It stops new sign-ins; existing sessions run until they end.
• Groups and group-based roles. See above.
• SSRF protection. The server fetches the issuer URL an administrator types in. That is fine while only the cluster operator sets issuers, but before multi-tenancy ships, a tenant's own administrator must not be able to point it at internal addresses. It needs a guard that refuses private ranges (by resolved IP), switchable off for self-hosted installs that really do use an internal provider.