OIDC

Sign in with any OpenID Connect provider, as a button on the login card.

Updated
On this page

Setup

Register a client with the provider using the redirect URI https://example.com/@oidc/{id}/callback, where {id} is the key you give the provider in the config and the origin is your site config's url. Then list the provider in the site config and keep client_secret in site/data/env.json:

{
    "url": "https://example.com",
    "addons": {
        "phlat/oidc": {
            "providers": {
                "sso": {
                    "name": "Company SSO",
                    "issuer": "https://id.example.com",
                    "client_id": "…",
                    "client_secret": "…",
                    "role": "editor"
                }
            }
        }
    }
}

Once a provider is listed, /@oidc (editors only) shows its exact Callback URL and Logout Callback URL to paste in, and what is still missing from its config.

The top-level url is the origin, pinned: the redirect URI is built from it and never from the request, so it always matches what the provider has registered. Without it the addon throws.

name is the button label (the id, capitalised, when left out). role is the role a new account gets on first sign-in; without a valid role, unknown identities are refused.

Issuers

issuer is the base of the provider's /.well-known/openid-configuration.

Provider issuer
PocketID https://id.example.com
Authentik https://auth.example.com/application/o/{application-slug}/
Keycloak https://keycloak.example.com/realms/{realm}
Google https://accounts.google.com

A provider that offers passkeys brings them along: the passkey is used at the provider, and the site never sees it.

Passwords

Password sign-in is off by default (auth.password is false). The login card then shows only the provider buttons, the login form refuses a posted password, and the profile page has no password form. Set it in the site config to turn passwords back on:

{
    "auth": { "password": true }
}

phlat user:password sets a password either way, but it only signs in while the option is on.

Accounts

A returning identity is matched by a hash of the provider and the token's sub, stored in the user's oidc field. Email is never used to match. A new identity creates a user named from preferred_username; a taken name gets a suffix, so it never signs in to an existing account.

Sign out

Signing out of PhlatPage ends only the PhlatPage session. The other direction is back-channel logout: when a user signs out at the provider, the provider calls https://example.com/@oidc/{id}/logout and every session that user has on the site ends. Providers name this differently: in PocketID it is the client's Logout Callback URL, so set it to https://example.com/@oidc/pocketid/logout. Others call it the back-channel logout URI.

The provider posts a signed logout_token. It is verified against the provider's published keys (RS256) and must name this site's client, carry the back-channel logout event and be recent. A request that fails any check is refused with a 400. A user the site has never seen is ignored.

To end a user's sessions from your own code, call $app->session->revoke($username): each of their sessions finds itself signed out on its next request.