SAML through a bridge

BROKA signs people in over OpenID Connect and LDAP, not SAML. If your identity provider speaks only SAML, put an identity provider that speaks both between the two: it accepts your SAML provider's sign-ins and hands BROKA an OpenID Connect one. This guide uses Keycloak, which can run beside BROKA; any provider that brokers SAML to OpenID Connect does the same.

How it fits together

People see BROKA's Sign in with button, Keycloak sends them on to your SAML provider, and they come back through Keycloak, signed in. To BROKA, each person is a Keycloak user: Keycloak's identifier for them, the e-mail address, and the groups Keycloak's mappers carried over from your SAML provider.

Use a Keycloak realm of its own for the bridge — broka in the examples below.

1. Add your SAML provider to Keycloak

In the realm, under Identity providers, choose SAML v2.0. Give it an alias — corp-saml below — and, with Use entity descriptor on, enter the address of your SAML provider's metadata under SAML entity descriptor. Then Add.

Keycloak publishes its own service-provider metadata for that provider, linked on its settings page as SAML 2.0 Service Provider Metadata, at https://<keycloak host>/realms/broka/broker/corp-saml/endpoint/descriptor. Register Keycloak with your SAML provider from it, as you would any application.

Keycloak checks the signatures of what your SAML provider sends against the certificate in its metadata, and by default expects the assertion itself to be signed. If a sign-in ends on Keycloak's Invalid signature in response from identity provider, have your SAML provider sign its assertions.

2. Carry the person's details and groups over

Under Groups, create a Keycloak group for each group BROKA should know. Then, on the identity provider's Mappers tab, Add mapper:

• an Attribute Importer for the e-mail address, the first name and the last name, each from the attribute name your SAML provider sends;
• an Advanced Attribute to Group mapper for each of those groups: under Attributes, the name of the attribute that carries your SAML provider's groups and the value that names the group; under Group, the Keycloak group. It puts the person in that group when the assertion carries that value.

On the identity provider's Settings tab, under Advanced settings, set Sync mode to Force, so that the mappers run at every sign-in rather than only the first: someone removed from a group at your SAML provider then leaves the Keycloak group at their next sign-in. Each mapper's Sync mode override can stay at Inherit.

Without the group mappers, the tokens Keycloak gives BROKA carry no groups from your SAML provider: BROKA then has nothing to map to teams, and creates no account at a first sign-in. Keycloak sends no groups at all for someone in none of its groups, and BROKA's Keycloak kind, step 5, reads that as no groups: someone removed from their last mapped group at your SAML provider leaves, at their next sign-in, the BROKA teams the mappings put them in. Teams they were added to by hand stay.

Turn on Trust Email, in the same Advanced settings, only if your SAML provider's addresses are ones its administrators control. Keycloak then marks those addresses as verified, which is what BROKA's linking by e-mail and its account creation read.

3. Add BROKA's client

In the same realm, create BROKA's client exactly as Single sign-on with Keycloak describes, with its Group Membership mapper, so that the groups from step 2 reach BROKA.

4. Skip Keycloak's own sign-in page

Optionally, to send people straight on to your SAML provider rather than show them Keycloak's sign-in page, open Authentication and the realm's browser flow. On its Identity Provider Redirector step, open Settings, give the settings an alias of their own, and set Default Identity Provider to the alias from step 1.

5. The provider in BROKA

Add a provider of the Keycloak kind, with the realm's issuer — https://<keycloak host>/realms/broka — and the client's ID and secret, and set Groups are sent as to Names. Test a sign-in: the result shows the address as verified when Trust Email is on, and the Keycloak groups the person is in, as paths such as /platform-admins. Map the groups as they arrive, and enable the provider.

Keycloak now decides who reaches BROKA, so look after its administration console as you would your SAML provider's.