Single sign-on

New in 0.4.0. Apograph can authenticate against an external identity provider alongside — or instead of — its own email and password.

The three adapters

One adapter covers most of the market, because the wire does not differ between OIDC vendors: a vendor is an issuer, a set of scopes and a claim mapping. Those are presets inside the OIDC package — createGoogleProvider, createEntraProvider, createOktaProvider, createAuth0Provider, createKeycloakProvider — not packages of their own.

GitHub and SAML are the exceptions that prove it. GitHub is OAuth2 with no identity token, so “verify” means spending the code and reading the profile back. SAML’s response is not a redirect at all — the provider POSTs a form to the callback.

Registering one

Adapters are constructed at the composition root and passed in IdentityPlugin’s second argument. Config holds the typed view of the environment; an adapter instance is not an environment value.

// apps/server/src/plugins.ts
import { IdentityPlugin } from '@apograph/identity-server';
import { createOidcProvider } from '@apograph/identity-provider-oidc';

IdentityPlugin(config.plugins.identity, {
    sso: {
        providers: [
            { name: 'okta', provider: createOidcProvider(config.plugins.identity.ssoProviders.oidc) }
        ]
    }
});

Register the callback URL with the provider exactly as ssoCallbackUrl(config, name) builds it. Most providers match that string byte for byte, and a trailing slash is a different URL to them.

Environment

Shared

SSO_PUBLIC_BASE_URL is configured rather than read from the request’s Host header, which a client controls and could therefore point at an origin of its choosing. Leave it unset when the admin and the API share an origin — the deployed shape, and the dev one where Vite proxies /api.

OpenID Connect

The provider is registered only when both the issuer and the client id are set. An issuer with no client id would be a sign-in button that can only fail, and every SSO failure looks the same, so whoever clicked it would learn nothing.

SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT is an operator’s assertion, never a default. Microsoft Entra ID simply never emits email_verified, so a first sign-in cannot claim an existing account until somebody says this directory is authoritative for the addresses it reports. A provider that sends email_verified: false is believed regardless.

GitHub

The address comes from GitHub’s verified-emails endpoint, never the public profile — a profile address is something a person can set to anything. An account with no verified address is refused outright, because there is no address there worth linking.

SSO_GITHUB_ORG shapes the chooser and nothing else. Apograph’s own rules decide who gets in.

SAML 2.0

SAML carries no verification claim at all, so emailVerified is always an operator’s assertion and defaults to false. Until you set it, a first sign-in cannot claim an existing account.

What a sign-in may do to an account

By default: nothing. It signs in accounts that already exist and are active, creates none, and changes nobody’s role. A first sign-in may claim an existing account only when the provider asserts the email is verified, and a pending or disabled account is refused exactly as on the password path.

Three things a deployment can turn on, each off by default.

Just-in-time provisioning creates an active account with no password the first time a verified profile arrives with no matching one.

Role mapping is plain code at the composition root — resolveRole returns a role key, or null to leave the role alone, which is also what no handler means. Two rules protect it: an unknown role key is logged and ignored rather than failing the sign-in, because a typo in a handler must not lock a directory out; and an account already holding admin is never demoted by a mapping. That grant is deliberate and a directory group is not.

Accepting an invitation with a work account. /start?invite=<token> carries the one-time token on the attempt. The callback checks that the address the provider vouched for is the one that was invited, burns the token, and activates the account without a credential. Following a spent link again as the same person just signs them in; anyone else following it is refused.

Turning passwords off

SSO_ALLOW_PASSWORD_LOGIN=false.

Ending a session because the provider says so

POST /api/auth/sso/:provider/backchannel-logout is the answer to the one thing operators assume SSO already does.

A session in Apograph is a row with a TTL, and disabling somebody in the directory does not reach it. Until this route existed, the honest answer to “we offboarded them, are they out?” was “within SESSION_TTL_SECONDS”.

The provider calls it directly, with no browser in the loop, so it works after the person has closed the tab. Two shapes of notification are handled differently on purpose:

• A sid ends only the sessions that provider session opened — somebody signed in on a laptop and a phone through two provider sessions keeps the other one.
• A sub with no sid ends every session the linked account holds. That is the offboarding case, and being blunt is the point.

Verification is the adapter’s. A provider that cannot verify a logout token does not implement it, and the route answers 404 rather than pretending to have acted — this endpoint is unauthenticated and reachable by anyone, so an unverified notification would be an open way to sign arbitrary people out.

For a provider with no back-channel logout, SSO_SESSION_TTL_SECONDS shortens SSO sessions alone: a partial mitigation, trading a re-authentication now and then for a smaller window after an offboarding.

What is audited

Three facts, deliberately not folded into the sign-in row: user.sso_linked, user.sso_provisioned and user.sso_role_mapped. “Somebody signed in” cannot answer “where did this account come from?”, which is the first question anyone reviewing an SSO deployment asks.

The sign-in row itself records the method and the provider, so the log can separate people who came in through the directory from those who still hold a password.

Writing an adapter

Each adapter’s own page covers its configuration in full; writing an SSO provider covers the port. In brief:

The SsoProvider port lives in @apograph/identity-domain, which imports nothing — no NestJS, no Drizzle, no jose. An adapter depends on the port without depending on the server plugin.

It states three obligations, and a conformance kit turns them into tests you run in your own suite:

1. complete verifies, or it throws. From the outside a decoded profile and a verified one are the same object, so an adapter that skips verification produces a sign-in that looks entirely normal.
2. subject is stable, issuer-scoped, and never the email. The link table keys on it.
3. emailVerified reports what the provider claimed. It is the only gate on claiming an account that already exists.

The core mints state, nonce and the PKCE verifier — adapters generate none of them. CSRF and replay defence is one rule, implemented once where it is tested once. One conformance check follows directly: authorize must not put the code verifier in the URL. Only its S256 challenge belongs there.