Identity providers
OpenID Connect and plain OAuth 2, configured while Keydra is running rather than through environment variables, with claim and group mapping per provider.
Providers are rows, not environment variables#
An identity provider is configured while Keydra is running, from the Access page, and takes effect without a redeploy.
One authorization-code implementation serves two kinds:
OpenID Connect — Keycloak, Entra, Google, Okta, Auth0. You give the Issuer and Keydra fetches the discovery document when you save, remembering where the endpoints are.
OAuth 2 — GitHub, GitLab. No id token, so the Authorization endpoint, Token endpoint and User endpoint are typed in.
What differs between the two is which URLs those are and what the claims are called, and both are configuration.
Discovery runs when a provider is saved, not at sign-in. A wrong issuer is answered where somebody is waiting and able to fix it, rather than making every sign-in depend on the provider’s slowest morning.
Every flow uses PKCE and a state cookie only Keydra can read. Both are what stand between the callback and signing somebody into an account they do not own.
A session produced by a provider is the same cookie a password produces. A provider is a different way of arriving at a session, not a different kind of session.
Claim mapping#
Which claim is which says what identifies somebody. The Subject claim is the one that
identifies them for good — sub for OpenID Connect, id at GitHub. Not the username:
usernames change.
Groups claim is optional. When it is set, membership of a mapped group is replaced at every sign-in by what the provider says — so removing somebody from a directory group removes their access — while groups nobody mapped are left alone.
LDAP is the one provider that is not this flow: no browser redirect, no authorization code — a bind, a search, and a password Keydra would read itself. Everything here is built on never seeing a password that is not its own.
Adding an identity provider#
-
You hold
idp:manage. -
KEYDRA_PUBLIC_URLis set, so the redirect comes back to the right address.
-
Go to Access and open the Sign-in tab.
-
Click Add provider.
-
Choose the Kind.
-
Give a Key — lowercase letters, digits and hyphens. It appears in the redirect URI, so it cannot be changed later.
-
For OpenID Connect, give the Issuer. For OAuth 2, give the Authorization endpoint, Token endpoint and User endpoint.
-
Give the client id and Client secret. The secret is stored encrypted and never sent back.
-
Set Scopes.
-
Under Which claim is which, set the Subject claim, Username claim, and optionally the Email claim, Name claim and Groups claim.
-
Copy the Redirect URI the form shows and register it with the provider exactly as it appears.
-
Save.
The row reads Endpoints known. Sign out and the login page offers Continue with {name} under Or sign in with.
A first attempt is usually refused because the redirect URI does not match. Copy it from the form rather than typing it.
Mapping provider groups to Keydra groups#
-
The provider sends a groups claim, and Groups claim names it.
-
Open the provider and find Group mappings.
-
Add a mapping: What the provider calls it, and the Keydra group somebody in it should join.
Sign in through the provider. The account’s memberships in mapped groups now match what the provider said.
Membership of a mapped group is replaced at every sign-in. Adding somebody to a mapped group by hand in Keydra will not survive their next sign-in — that is the point, and it is what makes removing them from the directory remove their access here.
Groups nobody mapped are left alone.