How to configure your Keycloak instance

Before you can connect Open Data Hub to your external identity provider, your Keycloak instance must be configured with the correct client, scopes, groups, and secrets. These ensure that users are authenticated with the right identity and permissions when accessing both the OpenShift cluster and the ODH dashboard. 

Prerequisites:

• An Amazon Web Services account.
• A Red Hat account.
• A configured ROSA cluster.
• Keycloak server (v24.x or later) with admin access.
• Keycloak must be deployed outside the OpenShift cluster (or use an existing instance).
• Keycloak must be publicly accessible from the ODH OCP cluster.

In this lesson, you will:

• Create realms in Keycloak.
• Configure client scopes.
• Create groups and users.
• Set token lifespans.

Create realms and clients

The first configurations to make to Keycloak are creating realms to manage any users, roles, and groups that will access your instance in the future, and clients that can request future authentication.

1.  Navigate to your Keycloak admin console.

2. Log in with admin credentials to verify your access (Figure 1). 
    

   

3. Once signed in, click Create Realm. 

4.  In the modal pop-up, set the Realm name to rosa-realm.

5.  Click Create. The new realm should appear in the realm dropdown once this is done (Figure 2). 
    

   

6. Next, create clients and ensure that all three redirect uniform resource identifiers (URIs) are configured correctly. 

7. Under the Clients menu, click Create Client.
8. Input the following information in the fields that appear.
   1. Client ID: odh-client
   2. Name: odh-client
   3. Client type: openID Connect
   4. Client Authentication: On
   5. Authorization: Off
   6. Authentication flow: Standard flow, Standard Token Exchange, OAuth 2.0 Device Authorization Grant

9. Once added, click Next (Figure 3).

   

10. Configure Valid redirect URIs  and replace ${CONSOLE_DOMAIN} with your ROSA cluster domain) with the following:
    1. https://console-openshift-console.${CONSOLE_DOMAIN}/auth/callback
    2. http://localhost:8080/*
    3. https://rh-ai.${CONSOLE_DOMAIN}/oauth2/callback
11. Set Configure Web Origins to + (permit all origins).

12. Click Save (Figure 4). 
     

    

Configure client scopes 

This next step is critical for role-based access control in OpenShift and for Open Data Hub to work correctly. The client scope mappers ensure that tokens issued by Keycloak include the user's audience, email, and group membership, which OpenShift and ODH use to determine what the user is authorized to access.

1. Navigate to Clients → odh-client → Client scopes → odh-client-dedicated.
2. Within Audience Mapper, select Configure a new mapper > By configuration, then click Audience.
3. Within the Audience mapper modal, input the following settings:
   1. Name: odh-client
   2. Included Client Audience: odh-client

4. Click Save (Figure 5). 
    

   

5. Within Audience Mapper, select Configure a new mapper > By configuration, then click User property.
6. Within the Email mapper modal, input the following settings:
   1. Name: email
   2. Property: email
   3. Token Claim Name: email
   4. Claim JSON Type: String
   5. Add to ID Token, Access Token, Userinfo, Token Introspection: ON

7. Click Save (Figure 6). 
    

   

8. Within Audience Mapper, select Configure a new mapper > By configuration, then click Group membership.
9. Within the Group membership mapper modal, input the following settings:
   1. Name: groups
   2. Token Claim Name: groups
   3. Full group path: OFF ⚠️ Important
   4. Add to ID Token, Access Token, Userinfo, Token Introspection: ON

10. Click Save (Figure 7). 
     

    

Create groups and users

Now that the client scope mappers are configured, you need to create the groups and users in Keycloak. Users added to the odh-admin group will receive cluster-admin access on OpenShift, matching the ClusterRoleBinding you created earlier. 

1. Within Keycloak, navigate to Groups and select Create Group.
2. When prompted to create a name, you must use the same one you entered during ClusterRoleBinding. Following this learning path example, you will enter odh-admin. 

3. Click Create (Figure 8). 
    

   

4. Next you will create users so they can be assigned to the newly created odh-admin group for cluster access. 

5. Navigate to Users then select Create new user.
6. In the Create user modal that appears, input the following:
   1. Username: ${ADMIN_USERNAME}
   2. Email: ${ADMIN_EMAIL}
   3. First name: ${ADMIN_FIRST_NAME}
   4. Last name: ${ADMIN_LAST_NAME}
   5. Email verified: ON

7. Click Create (Figure 9). 
    

   

8. Next, go to the Credentials tab and select Set password.

9. In the modal that appears, set the desired password and ensure the Temporary setting is turned off (Figure 10).
    

   

    

10. Navigate to the Groups tab.
11. Go to Join Group and select odh-admin. 

12. Click Join (Figure 11).
     

    

Get client secrets and set access token lifespans

To finalize your Keycloak setup, you must get the Client Secret value, as well as set your desired token lifespans. 

1. Navigate to Clients → odh-client → Credentials.
2. Copy the Client Secret value.

3. Save as KEYCLOAK_CLIENT_SECRET environment variable (Figure 12). The secret is a long alphanumeric string.
    

   

4. Next, you will set the access lifespans for your tokens for both single-sign on (SSO) session idle and gateway access. The ODH data science gateway runs an OAuth2 proxy whose default `GatewayConfig` cookie settings use a refresh interval of 1 hour (spec.cookie.refresh defaults to `1h` in the operator). If Keycloak issues shorter-lived access tokens or ends the SSO session sooner, the gateway may try to refresh while Keycloak already considers the session invalid. Users can see 401 Unauthorized, unexpected logouts, or errors loading the ODH dashboard.

5. Set both to at least 1 hour, or longer if your policy allows:

6. Realm settings → Tokens → Access Token Lifespan → 1 hour or more (Figure 13). 
    

   

7. Realm settings → Sessions → SSO Session Idle → 1 hour or more (Figure 14). 
    

   

Security vs. session length: Longer access token and SSO session idle values reduce repeated logins but keep IdP-issued sessions valid for a longer time, which may increase risk if a token or browser profile is compromised. Always follow your security policies and compliance requirements. If you cannot configure ≥ 1 hour in Keycloak, consider lowering GatewayConfig spec.cookie.refresh (and align spec.cookie.expire) so the gateway refreshes before the Keycloak session or access token expires. Be sure to test the dashboard flow, as timing mismatches are a common cause of gateway authentication errors.