Single sign-on

Ortha can authenticate against an external identity provider alongside — or instead of — email and password.

The three adapters

OIDC vendors differ only in issuer, scopes and claims, so they are presets in the OIDC package: createGoogleProvider, createEntraProvider, createOktaProvider, createAuth0Provider, createKeycloakProvider.

Quick setup

1. Scaffold with --sso sso-oidc (or sso-github, sso-saml), or copy the matching config/sso-*.ts and plugins.ts lines from a fresh app.

2. Register the callback URL with the provider, exactly:

   <SSO_PUBLIC_BASE_URL or your origin>/api/auth/sso/<name>/callback

3. Fill in .env:

SSO_OIDC_ISSUER=https://sso.example.com/realms/orthacms   # byte-for-byte, trailing slash included
SSO_OIDC_CLIENT_ID=orthacms
SSO_OIDC_CLIENT_SECRET=…                                     # optional for a public PKCE client
SSO_OIDC_NAME=keycloak                                       # permanent: appears in URLs and link rows
SSO_OIDC_LABEL=Keycloak
# Entra ID never sends email_verified:
# SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT=true

SSO_GITHUB_CLIENT_ID=…
SSO_GITHUB_CLIENT_SECRET=…          # required: no PKCE in this flow
SSO_GITHUB_NAME=github
SSO_GITHUB_LABEL=GitHub
# generated app:
SSO_GITHUB_ENTERPRISE_BASE_URL=     # https://github.acme.com for GHES
SSO_GITHUB_ORGANIZATION=            # cosmetic: shapes the account chooser

SSO_SAML_ENTRY_POINT=https://idp.example.com/sso/saml
SSO_SAML_IDP_CERT="-----BEGIN CERTIFICATE-----\nMIIC…\n-----END CERTIFICATE-----"
SSO_SAML_ISSUER=https://cms.example.com          # this CMS's entity id
SSO_SAML_SUBJECT_ATTRIBUTE=objectGUID            # when NameID is an email or transient
SSO_SAML_EMAIL_VERIFIED=true                     # your assertion; SAML has no such claim

4. Check it is registered:

curl http://localhost:3000/api/auth/sso

[{ "name": "keycloak", "label": "Keycloak", "kind": "oidc" }]

An empty [] means no provider is configured — only the password form shows. kind is oidc, oauth2 (GitHub) or saml.

Registering providers in code

Adapters are constructed at the composition root and passed as IdentityPlugin’s second argument. ssoProviders(config) in the generated plugins.ts registers what the environment configured. Add more, or a preset:

// apps/server/src/plugins.ts
import { createEntraProvider } from '@orthacms/identity-provider-oidc';

IdentityPlugin(config.plugins.identity, {
    sso: {
        providers: [
            ...ssoProviders(config),
            {
                name: 'contractors',
                provider: createEntraProvider({ tenantId: '…', clientId: '…', clientSecret: '…' })
            }
        ],
        // optional: map a directory group to a role; null leaves the role alone
        resolveRole: ({ profile }) =>
            profile.groups?.includes('cms-editors') ? 'contributor' : null
    }
});

• List order = sign-in button order. Nothing else.
• ssoCallbackUrl(config, name) from @orthacms/identity-server builds the exact callback string.

Environment

Shared

The last four are read by the product repository’s config/identity.ts. A generated app does not read them — add them to its ssoConfig():

// apps/server/config/identity.ts (generated app) — inside ssoConfig()
return defined({
    publicBaseUrl: readEnv('SSO_PUBLIC_BASE_URL'),
    requestTtlSeconds: readPositiveInt('SSO_REQUEST_TTL_SECONDS', 600),
    provisioning: when(readEnv('SSO_PROVISION_DOMAINS'), () => ({
        domains: readList('SSO_PROVISION_DOMAINS', ''),
        defaultRole: readEnv('SSO_PROVISION_ROLE') ?? 'viewer'
    })),
    allowPasswordLogin: readEnv('SSO_ALLOW_PASSWORD_LOGIN') !== 'false',
    sessionTtlSeconds: readOptionalPositiveInt('SSO_SESSION_TTL_SECONDS')
});

OpenID Connect

• Registered only when both issuer and client id are set.
• Auth0 issues with a trailing slash — omit it and tokens will not verify.
• Discovery is appended to the issuer’s path: https://sso.acme.com/realms/orthacms → …/realms/orthacms/.well-known/….
• EMAIL_VERIFIED_WHEN_ABSENT is your assertion that the directory owns its addresses (Entra ID). An explicit email_verified: false is always believed.

GitHub

• Registered only when both id and secret are set.
• The address comes from GitHub’s verified emails, never the public profile. No verified address → refused.

SAML 2.0

What a sign-in may do to an account

By default: nothing. It signs in existing active accounts, creates none, changes no roles. A first sign-in claims an existing account only when the provider says the email is verified. pending and disabled accounts are refused.

Three opt-ins:

• Just-in-time provisioning — creates an active, passwordless account for a verified profile with no match. Needs SSO_PROVISION_DOMAINS.
• Role mapping — resolveRole returns a role key, or null to leave the role alone. An unknown key is logged and ignored; an existing admin is never demoted.
• Accepting an invitation with a work account — /api/auth/sso/<name>/start?invite=<token>. The callback checks the verified address matches the invitation, burns the token and activates the account.

Turning passwords off

SSO_ALLOW_PASSWORD_LOGIN=false

Password recovery does not look at this switch: with mail configured, Forgot it? still sends an active member a reset link, and the password it sets still cannot sign in.

Ending a session because the provider says so

POST /api/auth/sso/:provider/backchannel-logout

Disabling someone in the directory does not reach an existing session row. This route does — the provider calls it directly, no browser involved.

• sid in the logout token → ends only the sessions that provider session opened.
• sub without sid → ends every session of the linked account (offboarding).
• A provider whose adapter cannot verify logout tokens gets 400 {"error":"invalid_request"}, the same as a token that fails to verify. An unknown provider name gets 404.

No back-channel logout at your provider? SSO_SESSION_TTL_SECONDS shortens SSO sessions to narrow the window, and since 0.13.0 an administrator can end them by hand: Members → the member → Sessions & access → Sign out everywhere (DELETE /api/users/:id/sessions).

What is audited

• user.sso_linked, user.sso_provisioned, user.sso_role_mapped — separate from the sign-in row.
• The sign-in row records the method and provider.

Writing an adapter

See writing an SSO provider. The SsoProvider port lives in @orthacms/identity-domain (no NestJS, Drizzle or jose). A conformance kit turns its three obligations into tests:

1. complete verifies, or throws.
2. subject is stable, issuer-scoped, and never the email.
3. emailVerified reports what the provider claimed.

authorize must never put the PKCE verifier in the URL — only its S256 challenge.