@substrat-run/oidc-rp
The Substrat platform's OpenID Connect relying party — written once so the security-critical verifier is not copied per app. The Dashboard and the control-plane Console both authenticate through it; the substrat login CLI brokers the same flow. It proves who a caller is (the ID token sub, and email) and nothing more — authorization stays in the kernel: roles, grants, and tenancy are never this package's concern.
It is the concrete form of the identity seam for the platform's own surfaces. The demo verticals are OIDC-only relying parties too, through @substrat-run/vertical-auth, against whatever issuer they are pointed at; none keeps a credential store, and demos/auth-server is the only workspace member that runs Better Auth — as an issuer. The platform apps share this one relying party against AuthHero.
What it is
- Standard Authorization-Code + PKCE, against the platform's AuthHero instance (an Auth0-compatible OIDC authority).
- Discovery-driven. The only wired-in value is the issuer URL; endpoints and signing keys come from
{issuer}/.well-known/openid-configuration. The ID token is signature-verified against the issuer JWKS. - Confidential client — the code-for-token exchange happens server-side with the client secret, never in the browser.
- Stateless. No KV, no D1. The short-lived PKCE/state/nonce rides a signed flow cookie (
sb_oidc_flow, 10-minute lifetime); the session is a signed JWT cookie (sb_session, 7-day lifetime). Both are HMAC-signed withSESSION_SECRET. - workerd-safe —
jose+ Web Crypto only, nonode:*. It runs in the same isolate as the app that mounts it.
Config is entirely runtime
Nothing is checked in; every value is a secret:
OIDC_ISSUER # e.g. https://auth.substrat.run — the only wired-in value
OIDC_CLIENT_ID
OIDC_CLIENT_SECRET # wrangler secret put …
SESSION_SECRET # signs the flow + session cookies
BASE_URL # optional — force the redirect origin, else derive from the request
OIDC_ALT_ISSUER # optional — a second issuer, see below. All three or none
OIDC_ALT_CLIENT_ID
OIDC_ALT_CLIENT_SECRET
OIDC_TOKEN_AUTH # optional — post (default) | basic, see below
OIDC_ALT_TOKEN_AUTH # the same, for the alternate issuer's clientHow the client secret reaches the token endpoint
OIDC_TOKEN_AUTH is post (the default: client_secret in the form body, which is what this package has always sent) or basic (an Authorization: Basic header, RFC 6749 §2.3.1, the id and secret form-urlencoded before they are joined). An issuer holds the method per client, as registered, and refuses the other: Better Auth's provider answers invalid_client: client registered for client_secret_basic cannot use client_secret_post. Discovery cannot settle it, because a server advertises every method it supports at all, so set it to what the client was registered with. The secret is sent in one place, never both. Any value but post, basic or empty refuses the login rather than guessing. OIDC_ALT_TOKEN_AUTH is the same setting for the alternate issuer's client.
A second issuer: ?idp=alt
/api/auth/login?idp=alt signs in through the issuer in OIDC_ALT_* instead of OIDC_ISSUER. It is for trying a new issuer before it is the default, and for keeping one that does not live on this platform for the day the default is down. The apps' own sign-in pages carry it for you: open the Console, the Dashboard or the builder studio as /?idp=alt and the redirect to login keeps it.
- Only that value. Anything else, or nothing, is the default issuer.
- No quiet fallback.
idp=alton a deployment without all threeOIDC_ALT_*values sends the browser toonError; it never signs the person in at the default issuer. - The choice rides the signed flow cookie, so the callback verifies the ID token against the issuer the person was sent to — its
issand itsaud— and a query string cannot move it afterwards. A token the other issuer signed is refused. - The redirect URI is the same for both (
/api/auth/callback): register it at the alternate issuer's client as well. - The session does not remember the issuer. It is the same app-signed session either way, so an expired one re-authenticates at the default. Federated sign-out reads the issuer off the login's ID token, so it ends the session at the issuer that made it.
The alternate issuer is trusted exactly as much as the default one, for every account, on every app that mounts these routes. Whoever controls it, or its client configuration, can sign in as any account the default issuer could. Treat its keys and its configuration like the default issuer's.
Identity is keyed the same way whichever issuer made the login, because the session does not record which one did. Anything keyed on sub (a Dashboard team, a vertical's owner seat) sees the sub the issuer returns, so an alternate issuer that returns a different sub is a different login there. The Console and control plane's staff roster is keyed on a verified address, so the same address is the same staff member at both.
To switch it off, delete the three OIDC_ALT_* secrets from the app. Blanking them in the env file you push from does not remove secrets the app already holds.
Surface
The high-level entry point is mountOidcRoutes(app, opts?), which wires three routes onto a Hono app — identically for both platform apps, because the only per-app difference is what happens after a session exists:
import { mountOidcRoutes, sessionFromHeaders } from '@substrat-run/oidc-rp';
mountOidcRoutes(app, { onSuccess: '/', onError: '/?error=auth' });
// mounts: GET /api/auth/login · GET /api/auth/callback · GET /api/auth/logout[?federated]
// elsewhere, resolve the current user from a request:
const user = await sessionFromHeaders(c.env, c.req.raw.headers); // SessionUser | nullSessionUser is { id, email?, name?, emailVerified? }. The last is the issuer's email_verified claim about email, carried through the session unchanged and three-state: true and false are the issuer asserting something, undefined is the issuer saying nothing — an IdP that never emits the claim, or a session minted before the field existed, for the rest of its seven days. mintSession signs it into the session JWT under its OIDC spelling, email_verified, so the mint and the read agree; verifySession hands it back as emailVerified.
An address is an identifier only when the issuer verified it
Anyone with an issuer account can put any address on it. Wherever the platform keys something on an address — the Console's staff roster, the builder studio's staff check, a Dashboard invite addressed to someone, the support desk's signed visitor identity — it asks identifyEmail(env, user), and by default only emailVerified: true passes (#1359):
import { identifyEmail, emailRefusalMessage } from '@substrat-run/oidc-rp';
const id = identifyEmail(c.env, user);
// { email } — verified: use it
// { email: null, refused } — 'unverified' (the issuer said false),
// 'unasserted' (no claim at all), or 'no-email'
if (!id.email) return c.json({ error: emailRefusalMessage(id.refused) }, 403);unasserted is refused like unverified, not trusted. It is what every session minted before the claim was carried looks like, so the message for it asks the person to sign in again; the platform issuer sends the claim on every login. Signing in is not gated: a session whose address is unverified is still a valid session, it just may not be anyone by address.
The rule has one switch, for an issuer that does not send the claim:
OIDC_ALLOW_UNVERIFIED_EMAIL=true # break-glass — admits an address the issuer did not verifyIt is a deployment-wide variable, never a request parameter, a roster column or a tenant setting, and only the exact string true turns it on. While it is on, each isolate logs a warning the first time it reads it and another line for every address it lets through, so the decision shows up in the logs.
The per-app step that stays in the app is exactly the interesting one: the Dashboard does a JIT tenant bootstrap on first login (a new user provisions their own tenant), while the Console does a staff-roster lookup (only a known staff actor gets in). Same session, two admission policies.
Signing out, locally and at the issuer
GET /api/auth/logout clears the session cookie and redirects to a same-origin returnTo. The issuer keeps its own session on its own domain, so the next "Sign in" is a silent re-authentication as the same person. GET /api/auth/logout?federated ends that one too, through OIDC RP-Initiated Logout: the issuer's end_session_endpoint, with this login's ID token as id_token_hint. The mounted callback keeps that token in its own cookie (sb_oidc_idt, scoped to the logout path, SameSite=Strict), and the logout route clears it on its one use — so the hint rides one request in the session's life, not every one. It is not sent on every federated sign-out, deliberately: Strict withholds the cookie from a cross-site navigation, so a hostile page linking to ?federated cannot hand the issuer a valid hint (logout CSRF against the issuer session). What that link gets is whatever the issuer does without one: a confirmation page where the issuer asks. The platform's auth server does not ask for a request naming an enabled client, so there the link does end the issuer session, and every app signed in through it hears by back-channel logout. It signs the person out and exposes nothing. The route also withholds the hint from an http: end-session endpoint (loopback excepted, for the dev issuer), because it is a signed assertion about who is signed in, travelling in a URL the browser keeps in history and Referer. A session minted before the callback began keeping the token has no hint either, until the next sign-in. Local sign-out happens first, always — an issuer that is down, advertises no end-session endpoint, or refuses the redirect URI can only leave its own session standing, never keep somebody signed in here.
The hint is what lets the sign-out be a straight redirect. Without it the issuer cannot tell a real sign-out from a link somebody was tricked into following, so the spec says it should interrupt with a Confirm logout page — whether it does is the issuer's choice, and Better Auth's provider does, which is the bug #1361 fixed. The platform's auth server confirms on the person's behalf for a browser GET that names an enabled client, so its page appears only for a request with no client_id or a form POST. Two conditions live at the issuer and are the same for a vertical: RP-initiated logout enabled for the client, and the exactpost_logout_redirect_uri the app will send on its allow-list. There are exactly two such values, both the app's origin plus a fixed path: / (or the onSuccess path) when the logout link carried no returnTo, and /api/auth/logged-out when it did. Register both. A returnTo is never sent to the issuer, because it differs per request (an invite link's /invite/<token>) and an exact-match list cannot hold it. Instead the logout route parks the path in a short-lived sb_oidc_return cookie — HttpOnly, SameSite=Lax (it is read on the issuer's cross-site redirect back), scoped to /api/auth/logged-out — and that route reads it once, clears it, and redirects there; a missing or unsafe value lands on /. The list is separate from the sign-in callbacks, so an origin alone or a callback URL registered for sign-in buys nothing at sign-out; the mismatch does not fail loudly, the person is signed out and simply left at the issuer. See signing out in vertical-auth.
Lower-level pieces are exported for callers that don't want the mounted routes — beginLogin / completeLogin (the two halves of the round-trip), mintSession / verifySession, sessionFromHeaders, federatedLogoutUrl, federatedLogout, and safePath (the open-redirect guard that permits only a same-origin absolute path for a returnTo: no scheme, no //host, no backslash and no ASCII control character, since a URL parser strips a tab or newline before resolving). federatedLogout(env, origin, local, idTokenHint?, defaultPath?) is federatedLogoutUrl for a caller that has a returnTo: it resolves to { location, returnTo? }, sending the issuer local when that is the default path and LOGGED_OUT_PATH otherwise, in which case the caller must park returnTo in a LOGOUT_RETURN_COOKIE cookie and serve LOGGED_OUT_PATH to read it back. LOGGED_OUT_PATH (/api/auth/logged-out) and LOGOUT_RETURN_COOKIE (sb_oidc_return) are exported so a composing caller and the mounted routes agree on them. completeLogin returns { user, session, returnTo?, idToken }, and the idToken is there for one reason: a caller composing its own logout must retain it and pass it to federatedLogoutUrl as the hint, or its federated sign-outs land on whatever the issuer shows without one — the confirmation page, at Better Auth. completeLogin returns the token rather than storing it because the function is stateless and owns no cookie: the mounted callback route is what calls it and writes the hint cookie, and a caller with its own storage keeps it wherever suits. (The substrat login broker is not such a caller — it bounces through the mounted routes and mints its bearer token from the session they leave with mintSession.) federatedLogoutUrl(env, origin, postLogoutPath, idTokenHint?) resolves to the end-session URL — post_logout_redirect_uri is origin + postLogoutPath, so that exact string is what the issuer must have registered — or null when the issuer advertises none or discovery fails; clear the session cookie before calling it, never after. It applies the http: rule above itself: the hint is dropped from a non-HTTPS, non-loopback end-session URL, and the redirect still happens without it.
Status
Real and in production — it is what signs you in to the platform apps today. 0.x: the surface is stable enough that two apps share it unchanged, but versioned as pre-1.0 until the platform's own auth surface settles.