Red Hat Build of Keycloak Configuration

Red Hat Build of Keycloak (RHBK) can act as an external authentication provider for OpenShift, issuing OIDC tokens that are presented to the cluster to access protected resources. This section describes how to configure an existing RHBK instance for this purpose.

This configuration is required when leveraging RHBK as an external authentication provider for all three deployment paths covered in this reference architecture (ROSA HCP, ARO HCP, and self-managed OpenShift).

Prerequisites

The following must be satisfied to integrate an OpenShift cluster with RHBK:

  • An existing RHBK instance. See the product documentation for installation steps.

  • Network connectivity between the OpenShift cluster and the RHBK instance.

  • Permissions in RHBK to create and manage a realm, or permissions within an existing realm.

Realm creation

A RHBK realm must exist with the required entities to integrate with OpenShift. You can use an existing realm or create a new one. In this reference architecture, a new realm named openshift will be created.

To create a new realm:

  1. Navigate to and sign in to the RHBK admin console.

  2. In the left navigation bar, open the realm dropdown and select Create new Realm.

  3. Enter openshift in the Name field.

  4. Click Create.

User and group management

To authenticate to an OpenShift cluster, at least one user must exist in the RHBK realm. This section creates two example users:

  • openshift_admin — a user with cluster administrator access

  • openshift_developer — a user with developer access

Users are placed in groups so that OpenShift can delegate permissions by group membership. Create the following groups in the realm:

  • openshift_admins — Users with administrator capabilities; this group is granted elevated access in the cluster.

  • openshift_developers — Users with development capabilities.

Creating groups

  1. In the openshift realm, select Groups in the left navigation bar.

  2. Click Create Group.

  3. Enter the group name (for example, openshift_admins).

  4. Click Create.

  5. Repeat until both openshift_admins and openshift_developers exist.

Creating users and assigning groups

Create openshift_admin in the openshift_admins group and openshift_developer in the openshift_developers group.

For each user:

  1. In the openshift realm, select Users in the left navigation bar.

  2. Click Create a new user.

  3. In the new user form:

    • Set Email Verified if desired (optional).

    • Username: for example, openshift_admin.

    • Email: for example, openshift_admin@redhat.com.

    • First Name and Last Name: as desired.

  4. Click Join Groups, select the appropriate group, then click Join.

  5. Click Create.

  6. Open the Credentials tab and click Set password.

  7. Enter the password in Password and Password confirmation; clear the Temporary checkbox.

  8. Click Save, then Save password.

Repeat for each user, assigning each to the appropriate group.

Custom scope for group membership

For group membership to appear in the OIDC token, a custom RHBK client scope must be created. A client scope controls which details are included in the generated token.

Creating the groups client scope

  1. In the openshift realm, select Client Scopes in the left navigation bar.

  2. Click Create client scope.

  3. Set Name to groups.

  4. Set Type to Default so the scope is automatically included in tokens.

  5. Enable Include in token scope.

  6. Click Save.

Adding a group membership mapper

  1. Open the groups client scope and go to the Mappers tab.

  2. Click Configure a new mapper.

  3. Choose Group membership.

  4. Set Name to groups.

  5. Set Token Claim Name to groups.

  6. Leave Full group path disabled.

  7. Click Save.

OAuth clients

RHBK OAuth clients are used for authentication from the OpenShift CLI and the OpenShift Web Console. A minimum of one client is required. However, for the purpose of this reference architecture, one client is created for the CLI and another is createdd for the web console.

OpenShift CLI client (openshift-cli)

  1. In the openshift realm, select Clients and click Create client.

  2. General settings:

    • Client ID: openshift-cli.

    • Click Next.

  3. Capability config: keep defaults and click Next.

  4. Login settings:

    • Valid redirect URIs: http://localhost (used by the oidc-login kubectl plugin).

    • Click Save.

Enabling Client authentication on this client improves security but may add steps for users or automated systems.

Confirm the groups scope is assigned to openshift-cli:

  1. On the Clients page, select openshift-cli.

  2. Open the Client scopes tab.

  3. If groups is not listed, click Add client scope, select groups, then click Add and choose Default.

OpenShift Web Console client (openshift-console)

  1. In the openshift realm, select Clients and click Create client.

  2. General settings:

    • Client ID: openshift-console.

    • Click Next.

  3. Capability config:

    • Enable Client authentication (required for the confidential client type).

    • Click Next.

  4. Login settings:

    • Valid redirect URIs: must match the OpenShift Web Console callback URL. Use the following command based on your OpenShift cluster type to determine the correct URL:

Environment Command

Self-managed OpenShift

echo $(oc whoami --show-console)/auth/callback

ROSA HCP

echo $(rosa describe cluster -c $ROSA_CLUSTER_NAME -o json | jq -r '.console.url')/auth/callback

ARO HCP

echo $(az rest --method GET --uri "/subscriptions/${ARO_SUBSCRIPTION_ID}/resourceGroups/${ARO_RESOURCE_GROUP}/providers/Microsoft.RedHatOpenShift/hcpOpenShiftClusters/${ARO_CLUSTER_NAME}?api-version=2024-06-10-preview" | jq -r '.properties.console.url')/auth/callback

  1. Click Save.

Confirm the groups scope is assigned to openshift-console:

  1. Open the Client scopes tab for openshift-console.

  2. If groups is not listed, click Add client scope, select groups, then click Add and choose Default.

Locating the console client secret

Since openshift-console is configured as a confidential client, RHBK generates a client secret by default to authenticate against the RHBK server. This secret is required when configuring the external authentication provider in OpenShift.

  1. In the openshift realm, select Clients in the left navigation bar.

  2. Select openshift-console.

  3. Select the Credentials tab.

  4. The secret is in the Client Secrets section.

Next steps

With the RHBK realm, users, groups, scopes, and OAuth clients configured, you can now integrate the OpenShift environment with this RHBK instance.

Return to the deployment path for your environment:

  • ROSA HCP — Configuring the external authentication provider for ROSA HCP

  • ARO HCP — Configuring the external authentication provider for ARO HCP

  • Self-Managed OpenShift — Configuring the external authentication provider for Self-Managed OpenShift