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.
Prerequisites
Section titled “Prerequisites”- an OIDC provider where you can create a client — note its client id
and its issuer URL (the base the
.well-known/openid-configurationdocument 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).
- Open Settings → Server → Single sign-on and switch to OpenID Connect.
- 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.
- At the provider, register the redirect
https://<your-server>/oidc/callbackon that client. - 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). - 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.
- 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.
- Take a login: the web connect screen shows Sign in with OpenID
Connect, or open
https://<your-server>/oidc/logindirectly.
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.
How sign-ins match existing accounts
Section titled “How sign-ins match existing accounts”A sign-in through the identity provider finds its account in this order:
- 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. - A verified email, on both sides. Otherwise the sign-in matches an
account by email only when the provider sends
email_verified: trueand 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.
Providers that do not send email_verified
Section titled “Providers that do not send email_verified”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.
Check your configuration from this page
Section titled “Check your configuration from this page”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.
Test sign-in at your provider
- Your provider's sign-in or consent page: the client ID and redirect URI are registered. You can close the tab.
- An error at your provider: it names what to fix, usually a redirect URI that is not registered or an unknown client ID.
- Your server's "Sign-in failed" page: also a pass. The provider accepted the request and sent you back; your server refuses it only because this page started the sign-in, not your server.
Troubleshooting
Section titled “Troubleshooting”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.