Skip to content

Configure user federation

This guide shows how to configure the Keycloak instance on the Garden cluster to allow users defined in a customer-side Keycloak instance (the Remote Keycloak) to access the OSC Dashboard.

Realm roles associated with the user in the Remote Keycloak will be accessible by the OSC Dashboard. This enables allowing/denying to access OSC Dashboard functionality to users in Remote Keycloak by editing their roles directly in Remote Keycloak.

Disclaimer

OSC don't take responsibility for any issues, outages caused by incorrect Realm settings performed by the Customer.

Please be aware that misconfiguring the Realm may lead to authentication and security issues.

Note

There are multiple ways to manage users and groups, map roles and other authorization settings. This varies from organization to organization.

This example shows the configuration for connecting a remote customer-owned keycloak instance with OSC keycloak - for other IdP providers below steps might vary.

To learn more, please see the Keycloak documentation.

Before you begin

Request additional roles

To be able to manage Identity provider settings in the Gardener Keycloak, your user may need to be configured with additional Client Roles.

Please contact OSC to provide you the necessary rights.

Set up certificate trust

Before the two Keycloak instances can communicate, The Garden Keycloak needs to be set up to trust the HTTPS certificate configured for the Remote Keycloak.

You need to provide all Root and Intermediary certificates of the Certificate Authority which issued the Remote Keycloak's certificate.

Please contact OSC to set up the trust.

Set up the Remote Keycloak

The following changes are necessary on the Remote Keycloak instance.

Start by selecting the realm containing the users by pressing Manage realms and selecting the Realm's name.

Client scope

  • Create a Client scope by selecting Client scopes in the left-hand sidebar and clicking on the Create client scope button.
  • Edit the Client scope:
    • Set Name: groups
    • Select Protocol: OpenID Connect
  • Save the Client scope and continue to edit it.
  • Add a Mapper by selecting the Mapper tab and clicking on Configure a new mapper.
  • Select the User Realm Role mapping
  • Edit the new Mapper:
    • Set Name: groups
    • Set Token Claim Name: groups
    • Set Add to ID token: On
  • Save the Mapper

Client

  • Create a new Client by selecting Clients in the left-hand sidebar and clicking on the Create client button. The Create client wizard is displayed.
  • Edit the new Client:
    • Select Client type: OpenID Connect
    • Set Client ID to a meaningful name, e.g. the name of the Garden cluster
  • Click on Next and continue editing on the next page:
    • Set Client authentication: On
  • Click on Next and continue editing on the next page:
    • Set Valid redirect URIs: Set the URL based on the name of the Garden cluster and the region (MDB/FFM): https://sso.apps.<name of garden>.<ffm|osc>.osc.live/*
  • Click on Save to finish the wizard. After the Client's page is displayed, continue the editing.
  • Select the Credentials tab, and display the Client Secret. Note it down, you will need to enter it in the Garden Keycloak.
  • Select the Client scopes tab and click on the Add client scope button.
  • Select groups (created in the previous step) and click on Add. Select Default from the pop-up menu.
  • Save the Client.

Set up Garden Keycloak

The following changes are necessary on the Garden Keycloak instance.

Start by selecting the realm containing the users by pressing Manage realms and selecting the customer realm.

Identity Provider

  • Create a new Identity provider by selecting Identity providers in the left-hand sidebar, and
    • If this is the first Identity provider for this realm: Select Keycloak OpenID Connect from the User-defined list
    • If there are already configured Identity providers for this realm: Click on the Add provider button, and select Keycloak OpenID Connect from drop-down menu.

  • Edit the Identity provider's properties:

    • Set Alias: add a meaningful name, e.g the name of the Remote Keycloak

    • Set Discovery endpoint: enter in the form https://<remote keycloak hostname>/realms/<your realm>/.well-known/openid-configuration. Make sure the correct realm's name is included in the URL.

      Note

      The color of the text box's border should change to green as a sign that the communication between the two Keycloak instances was successful.

      If the color changes to red, it was not possible to connect to the Remote Keycloak — check the URL, make sure the Remote Keycloak is reachable network-wise, and check the correctness of the provided CA certificate.

    • Set Client ID: enter the Client ID configured on the Remote Keycloak
    • Set Client Secret: set the Client Secret noted down from Remote Keycloak
    • Check Redirect URI: should match the Valid Redirect URIs set on Remote Keycloak
    • Add the new Identity Provider by clicking on Add and continue editing it
    • Note that the URLs in the section OpenID Connect settings were auto-configured based on the Discovery endpoint
    • Save the Identity provider

Role mapping

A Mapper needs to be created for each Realm Role associated with users in the Remote Keycloak, which need to be mapped to Garden Keycloak and the OSC Dashboard.

  • Open the Identity provider created in the previous step by selecting Identity providers in the left-hand sidebar, and clicking on its name on the list.
  • Add a Mapper by selecting the Mappers tab and clicking on Add mapper:
    • Set Name: enter the name of the Realm role from the Remote Keycloak
    • Set Sync mode override: Force
    • Set Mapper type: External Role to Role
    • Set External Role: Type in role from the Remote Keycloak
    • Set Role: click in Select Realm and select Realm roles from the drop-down menu
    • Select the Realm role from the list and click on Assign
  • Save the Mapping

Example

As an example, if you want:

  • to provide Viewer access to OSC Dashboard, which is tied to the customer:gardener:viewer Realm role,
  • to a user in the Remote Keycloak, which has the example-viewer Realm role,

set up the mapping in the following way:

  • External Role: example-viewer
  • Role: customer:gardener:viewer

Login

The login procedure changes.

  • Open the OSC Dashboard's URL
  • Click on REALM then select the "customer" realm, and click on LOGIN.
  • On the next login screen, click on the newly created Identity provider's name on the Or sign in with menu.
  • Use the username and password of a user defined in the Remote Keycloak.

After the OSC Dashboard is displayed, click on the user icon in the top right corner, then click on MY ACCOUNT. The Realm role mapped from the Remote Keycloak should be included in the Groups list.