Skip to content

Keycloak

This page explains how to configure Keycloak as an OpenID Connect (OIDC) identity provider for Fusion Metadata Registry (FMR).

The examples below assume that:

  • FMR is registered in a Keycloak realm as an OpenID Connect client
  • the FMR redirect URI is https://<fmr-host>/ws/fusion/oauth/callback
  • FMR authorisation in FMR is based on the groups claim returned by Keycloak

Register FMR as a confidential client

In most deployments, FMR should be registered as a confidential client so that it can authenticate to Keycloak with a client secret.

To create the client in Keycloak:

  1. Open the Keycloak Admin Console and select the realm that will authenticate FMR users.
  2. Go to Clients.
  3. Select Create client.
  4. Set Client type to OpenID Connect.
  5. Enter a Client ID such as fmr.
  6. Optionally enter a Name such as Fusion Metadata Registry.
  7. Select Next.
  8. Enable Client authentication.
  9. Ensure Standard flow is enabled.
  10. Select Next and then Save.

After the client has been created:

  1. Open the client configuration.
  2. On the Settings tab, add the FMR callback URL to Valid redirect URIs:
https://<fmr-host>/ws/fusion/oauth/callback
  1. If required for your environment, also set Home URL, Root URL, or Web origins.
  2. Save the changes.

Get the client ID and client secret

Use the values from the Keycloak client in the FMR OIDC configuration:

  • Client ID: the value entered when the client was created, for example fmr
  • Client Secret: open the client's Credentials tab and copy the generated secret

Enter these into FMR:

  • Issuer URI: https://<keycloak-host>/realms/<realm-name>
  • Client ID: the Keycloak client ID
  • Client Secret: the secret from the Credentials tab

Configure Keycloak to emit the groups claim

FMR uses group membership for role-based authorisation, so Keycloak must include a groups claim in the token or user information returned during sign-in.

One straightforward approach is to add a Group Membership mapper to the client:

  1. Open Clients and select the FMR client.
  2. Open Client scopes.
  3. Select a client scope that is applied to the client, such as the dedicated client scope for the client, or create a new scope if you prefer to keep the mapping separate.
  4. Open the scope's Mappers tab.
  5. Select Add mapper.
  6. Choose By configuration.
  7. Select Group Membership.
  8. Configure the mapper with values similar to these:
Setting Value
Name groups
Token Claim Name groups
Claim JSON Type String
Add to ID token Enabled
Add to access token Enabled
Add to userinfo Enabled
Full group path Usually disabled
  1. Save the mapper.

Note

If Full group path is enabled, Keycloak emits values such as /fmr-admin instead of fmr-admin. In most cases, it is simpler to leave this disabled and use plain group names in both Keycloak and FMR role mappings.

Assign users to groups

Create the groups that you want FMR to receive, then assign users to those groups.

Create groups

  1. Go to Groups in the Keycloak Admin Console.
  2. Create the groups that FMR will use, for example:
  3. fmr-admin
  4. fmr-publisher
  5. fmr-reader

Add users to groups

  1. Go to Users.
  2. Open the user record.
  3. Open the Groups tab.
  4. Select Join Group.
  5. Choose the required group and confirm.

After the user signs in through Keycloak, FMR can use the returned groups claim together with its role mapping configuration to grant the correct permissions.

Optionally configure FMR as a public client with PKCE

Use a public client only if your deployment does not allow FMR to hold a client secret. In this mode, FMR should use PKCE instead of a client secret.

To configure this in Keycloak:

  1. Open Clients and select the FMR client.
  2. On the Settings tab, disable Client authentication.
  3. Ensure Standard flow remains enabled.
  4. Save the client.
  5. Open the Advanced tab.
  6. Set Proof Key for Code Exchange Code Challenge Method to S256.
  7. Save the client.

When using the public client configuration in FMR:

  • enter the Client ID
  • leave Client Secret blank

References