Built with Chinaski

Set Up SSO

Chinaski supports single sign-on through any standard OAuth 2.0 / OpenID Connect provider (authorization-code flow). One provider per site. This guide covers both sides: registering the app with your identity provider, and filling in the settings.

What to register at your identity provider

  1. Create an OAuth/OIDC application (client) of the standard “authorization code” type.
  2. Give your provider the redirect URL the CMS will use:
https://<your-site-domain>/auth/sso/callback

(Your provider may call it Redirect URI, Callback URL, or similar.) This needs to be the exact address your admin is reachable at.

  1. Note the granted scopes: Chinaski signs in with openid email profile and reads the user’s sub, email, and (if present) email_verified claims.
  2. Copy the three endpoints your provider exposes: almost all compliant providers publish the same trio under names like “Authorization endpoint,” “Token endpoint,” and “Userinfo endpoint.”

What to fill in Chinaski

Under Settings → Security, enable the OAuth checkbox. The endpoint fields appear once it’s on:

  • Client ID: the application/client ID from your provider.
  • Client Secret: paste it once; it’s stored encrypted and the field stays blank afterward (“leave blank to keep existing” semantics, like other credentials).
  • Authorization URL: your provider’s authorize endpoint (typically ends in /authorize).
  • Token URL: your provider’s token endpoint.
  • Userinfo URL: your provider’s userinfo endpoint.

The SSO button appears on the sign-in page only when all of the above plus the secret are saved: a partially filled config checks itself rather than half-working.

How sign-in works afterward

  1. The admin login page shows a “Sign in with SSO” button (alongside the normal password form, which still works).
  2. Clicking it sends the browser to your provider, with a one-time random state to keep the exchange safe.
  3. After the provider authenticates the person, the flow verifies the response’s state and exchanges the code for an identity.
  4. Then account resolution happens, in this order:
    • Already-linked user: recognized by their provider identity (sub).
    • Existing account by email: if the email matches a user’s email and the provider confirms it. That account gets linked to the SSO identity; their password is untouched.
    • Brand-new person: an account is created automatically as an editor with a unusable random password; the audit log records the auto-creation.
  5. The session is the standard 8-hour admin session; SSO users are normal users once signed in.

Account rules worth knowing

  • Editor by default. SSO-created accounts are editors; promote people to admin manually.
  • Only one provider slot. If you need two identity providers, that’s not something the current software supports; pick one.
  • Email matching trusts the provider’s confirmation semantics. If the provider explicitly marks an address unverified, sign-in is refused (and logged). If the provider doesn’t send a verification flag at all, which many OIDC providers do for confirmed accounts, Chinaski treats the address as verified. If your IdP allows unverified emails and you don’t want that, register email-verification enforcement there.
  • Provisioned users have no password. A random password is set that nobody knows; those users get in by SSO alone, or an admin emails them a password reset.
  • Locked or logged-out? Standard session rules apply: suspension still blocks SSO users exactly as it does password users; password changes/reset signs people out regardless of how they signed in.

Troubleshooting

  • The SSO button doesn’t appear: one required field (or the enable checkbox) is empty. Check all five.
  • “Invalid OAuth state” after returning from the provider: usually the callback ran in a different session/browser than it started in (cookies blocked, or the admin domain mismatched), or the user took too long on the provider’s page. Try again; if it persists, check that the admin URL in the address bar exactly matches the registered redirect URI.
  • “Sign in with SSO” missing from the login page: the configuration is incomplete or the checkbox is off; the fields only become part of the flow when all of them are filled.
  • “Email not verified” for a known user: the IdP explicitly said the account’s email is unverified; fix on the provider side (or set their email in the CMS to a verified one).
  • Created account is an editor, not what was expected: that’s the auto-provision rule; adjust roles in the admin users screen.

The short version

Register /auth/sso/callback as the callback at any standard OAuth/OIDC provider, fill in five fields under Settings → Security (enable toggle + client ID + encrypted secret + three endpoint URLs), and the login page gains an SSO button that signs users in, linking existing accounts by confirmed email, and creating editors automatically for new people.

Read this site in