Single sign-on with Keycloak

This guide connects BROKA to a Keycloak realm over OpenID Connect: a client in Keycloak, a provider in BROKA, and the groups that put people in BROKA's teams. What each BROKA setting does is described on Single sign-on.

In BROKA, first

In Settings ▸ Security ▸ Single sign-on, choose New provider, then OpenID Connect and Keycloak, and give it the name people will see on the sign-in page and a Slug, part of the address Keycloak sends people back to. The sheet's Give your identity provider these section then shows the Redirect URI Keycloak needs; switch on Also sign out of at the foot of the sheet if BROKA should also sign people out of Keycloak, and the section shows the Sign-out redirect URI as well. Keep the sheet open.

In Keycloak

1. In the admin console, in your realm, open Clients ▸ Create client: client type OpenID Connect, and a client ID such as broka.
2. Under Capability config, turn Client authentication on and keep the Standard flow. BROKA needs no other flow. BROKA always uses PKCE, so Require PKCE can be on.
3. Under Login settings, put BROKA's Redirect URI in Valid redirect URIs. If BROKA should also sign people out of Keycloak, put BROKA's Sign-out redirect URI in Valid post logout redirect URIs. Save.
4. On the Credentials tab, keep the Client Id and Secret authenticator and copy the Client Secret.

Groups

Keycloak puts no groups in its tokens until it is asked to. On the client's Client scopes tab, open its dedicated scope — broka-dedicated for a client named broka — and choose Configure a new mapper (Add mapper ▸ By configuration once the scope has mappers) and Group Membership: give it a name, set the Token Claim Name to groups, and keep Add to ID token on.

With Full group path on, as it is by default, groups arrive as paths such as /platform/broka-admins, which keeps two groups of the same name in different places apart. Map them as they arrive.

Keycloak sends no groups at all for someone in none of the realm's groups, and a provider of the Keycloak kind reads that as no groups. So removing someone from their last mapped group in Keycloak takes them, at their next sign-in, out of the BROKA teams the mappings put them in; teams they were added to by hand stay.

Back in BROKA

• Issuer URL: your realm's address, https:// followed by Keycloak's host, /realms/ and the realm's name.
• Client ID and Client secret from steps 1 and 4.
• Scopes: the default, openid profile email.
• Under Claim names, set Groups are sent as to Names. The claim names themselves fit Keycloak as they are.

Save, then Test sign-in. The result shows what Keycloak sent — the e-mail address and whether it is verified, and the groups. When it has passed, map the groups under Group mappings, and Enable the provider.

Accounts

Keycloak sends email_verified from the user's Email verified setting, so it means what your realm makes it mean. If people can set their own address there without verifying it, leave Link existing accounts by e-mail off.

A second factor

BROKA records a sign-in as made with a second factor when Keycloak's token says so in amr, and Keycloak fills amr only from values you give the steps of its browser flow. Under Authentication, duplicate the browser flow, bind the copy as the browser flow, and give each step's settings an Authentication Reference and an Authentication Max Age (default.reference.value and default.reference.maxAge): pwd on the password form, otp on the one-time-code form, and as the maximum age your realm's longest session in seconds. Without a maximum age, Keycloak names a step only in a token issued in the same second as that step, so most sign-ins would arrive without it. Test sign-in shows whether a second factor came through.

Signing out

With Also sign out of Keycloak switched on, signing out of BROKA ends the Keycloak session in that browser, and Keycloak sends the person back to BROKA's sign-in page — the address registered in step 3.

A provider that speaks only SAML

Keycloak can stand between BROKA and an identity provider that speaks only SAML: it accepts that provider's sign-ins and hands BROKA an OpenID Connect one; see SAML through a bridge.