Skip to content

Connect an OpenID Connect provider

Use this guide when your identity provider speaks OpenID Connect rather than SAML. Any OIDC-certified issuer works — Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace and friends all follow the same steps; only the spot where your provider shows the values differs.

  • an OIDC provider where you can create a client — note its client id and its issuer URL (the base the .well-known/openid-configuration document lives under), plus its client secret when the client is the confidential kind (public PKCE clients have none),
  • a Control Center server you administer (the server owner).
  1. Open Settings → Server → Single sign-on and switch to OpenID Connect.
  2. Fill in the Issuer URL and the Client ID and the Client secret (optional) when the provider issued one. Control Center discovers the endpoints from the issuer’s standard discovery document — no per-provider configuration.
  3. At the provider, register the redirect https://<your-server>/oidc/callback on that client.
  4. If your groups live under a claim other than groups, set the Groups claim name; map groups to roles if you want (SSO can never grant the owner role).
  5. Choose the membership policy (auto-add to every workspace, or require per-workspace invites), turn on Use OpenID Connect for sign-in and press Save connection.
  6. Press Test connection — the server fetches the issuer’s discovery document and confirms its endpoints, so a green toast means everything short of the browser round-trip works. To check the client registration too, use the checker below.
  7. Take a login: the web connect screen shows Sign in with OpenID Connect, or open https://<your-server>/oidc/login directly.

Claims (email, name, groups) are read from the issuer’s token endpoint over TLS by your server — the browser never supplies them, so no local JWT signature verification is involved. The client should be allowed to request the openid profile email scope, which is exactly what Control Center asks for.

Because that TLS channel is the only thing authenticating the claims, the issuer URL must be https — a plaintext issuer would let any on-path attacker forge identities wholesale. http is accepted for loopback issuers (localhost, 127.0.0.1, ::1) only, for local development.

A sign-in through the identity provider finds its account in this order:

  1. The pinned identity. The first SSO login pins the provider’s subject (issuer plus sub) to the account. Every later login with that subject is that account.
  2. A verified email, on both sides. Otherwise the sign-in matches an account by email only when the provider sends email_verified: true and the account’s address is verified too. An address is verified when SSO or SCIM set it, or when the server owner confirmed it. The owner’s own address counts.

Email addresses are stored and shown in lower case, and matching ignores case. A verified address identifies an account only when exactly one account holds it; if two accounts hold the same verified address, it matches neither.

An address someone typed in their own profile, or one typed on an invite, is not verified and matches nothing. Editing an address clears its verified state until someone vouches for it again. A sign-in never matches by username.

When nothing matches, the sign-in creates a new account if Provision unknown users on first login is on, and is refused if it is off.

Before you turn SSO on for people who already have accounts

Section titled “Before you turn SSO on for people who already have accounts”

Confirm their addresses first. Open Settings → Server → People, where each account shows Email not confirmed until someone has vouched for it, and use Confirm email on each person’s row. Only the server owner sees this list. Without it, each of those people either gets a second account on their first SSO login, or is refused when provisioning unknown users is off.

A person sees “Only you have entered this address. Single sign-on won’t match it until the server’s owner confirms it.” under the email field of their own profile while their address is unconfirmed.

Some providers leave the claim out. Microsoft Entra ID does by default. A missing claim is not a yes, so with such a provider a sign-in matches only by the pinned identity, and a person’s first login can never find their existing account by email. Provisioning the account with SCIM does not help that first OIDC login. The practical routes are:

  • leave Provision unknown users on first login on and let the first login create the account, or
  • configure the provider to emit email_verified, then confirm the matching addresses as above.

The checker below runs in your browser. It fetches your issuer’s discovery document directly, so this site never sees it, and applies the server’s rules: an https issuer that matches the document, endpoints on the issuer’s own origin, PKCE S256 and the token auth method your client type needs. With a client ID and server address, it can open a test sign-in that shows whether the client and its redirect URI are registered. It never asks for the client secret.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Needed for the test sign-in.

Client type

Never paste the secret here. The check only needs to know whether one exists.

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

For providers that block other sites from reading it.

Someone got a second account after SSO was turned on

Section titled “Someone got a second account after SSO was turned on”

Their existing account’s address was not verified when they first signed in with SSO, so the sign-in did not match it and created a new account. That happens when the address was typed in their profile or on an invite and the server owner had not confirmed it, or when the provider did not send email_verified: true. A new account whose provider vouched for the address takes that address, and the older account that only had it typed loses it.

To avoid it for the next person, confirm addresses in Settings → Server → People before they sign in. For someone who already has two accounts, the new one is pinned to their SSO identity, so it is the one their logins will use from now on.

“This account is already linked to a different SSO identity”

Section titled ““This account is already linked to a different SSO identity””

The sign-in matched an account by its verified email, but that account is already pinned to another subject or another issuer: a different user at the provider, the same person under a new provider, or an account SCIM created under its own identifier. The pinned account refuses every other identity, so a recycled address at the provider cannot take it over. Sign in with the identity the account was first linked to.