Skip to main content

Keycloak

You can connect your Keycloak-instance as an Auth Provider for Seatsurfing.

1. Configure your Keycloak-instance​

  1. Log in to your instance' administration console.
  2. Goto Clients and click Create.
  3. Choose a Client-ID, select openid-connect and enter as Root URL the complete URL of your Seatsurfing installation and click Save.
  4. Now Change Access Type to confidential.
  5. Click Save, in the navigationbar "Keys" will appear.
  6. At "Keys" you can copy the secret for the next step.

2. Configure Seatsurfing​

  1. Log in to Seatsurfing's Administrator UI.
  2. Navigate to Settings and add a new Auth Provider.
  3. Select the Keycloak template.
  4. Paste the Client ID you have chosen in keycloak into the "Client ID" field.
  5. Paste the Secret Value into the "Client Secret" field.
  6. Change all keycloakhost.sample to your hostname and optional master to your realm.
  7. Save the Auth Provider.
  8. Copy the Callback URL which is displayed right after saving.

3. Finish Keycloak Configuration​

  1. Head back to the Client you've created in the Keycloak admin-console in Step 1.
  2. Change Valid Redirect URIs from https://...../* to /auth/xxxxxc/callback

4. Assign Roles and Groups Automatically (optional)​

Seatsurfing can assign roles and group memberships from the groups Keycloak reports, so that access is managed centrally in Keycloak rather than separately in Seatsurfing.

Send groups in the token​

Keycloak does not include group membership by default. Add a mapper to the client:

  1. In the Keycloak admin console, open your client, then Client scopes and the client's dedicated scope.
  2. Add mapper → By configuration → Group Membership.
  3. Name it groups, set Token Claim Name to groups, and enable Add to userinfo.
  4. Leave Full group path on to receive paths such as /engineering/backend, or turn it off to receive plain names such as engineering.

Map the groups in Seatsurfing​

  1. Open the auth provider under Settings → Auth Providers.
  2. Set Groups field to groups — the claim name from the mapper above.
  3. Save, then add one row per mapping under Automatic assignment: the group as Keycloak reports it, and the Seatsurfing role or group it should grant.

Enter the group exactly as Keycloak sends it. With Full group path enabled that means the leading slash and the full path, /engineering/backend, not backend — two groups under different parents can share a leaf name.

What reconciliation does​

The mappings are applied on every login through this provider:

  • A user in a mapped Keycloak group receives the role or group membership.
  • A user no longer in that group loses it again at their next login.
  • Roles and groups assigned by hand in Seatsurfing are never touched, so the two can be combined.

A change in Keycloak therefore takes effect the next time the user signs in, not immediately.

One case is deliberately refused: if applying the mappings would leave the organization without any administrator, the roles are left as they are and a warning is written to the server log. Removing the last administrator has to be done deliberately in Seatsurfing, not by accident in Keycloak.

See Roles and Permissions for what the roles themselves grant.