Version: 1.3.15

Keycloak Integration

This page describes how to set up a Keycloak client to integrate with Certifai.

For additional instructions and form updates for subsequent versions refer to the latest Keycloak documentation portal.

Step 1: Create a Client

  1. Login to your Keycloak Admin Console.
  2. Click Clients in the left panel.
  3. On the Client list page click Create.
  4. Enter a simple alpha-numeric string as the Client ID (e.g. certifai-dev).
  5. Select openid-connect as the Client Protocol ID.
  6. Enter the base URL of Certifai as the Root URL.
  7. Click Save

keycloak-create-client

  1. On the Settings tab.
  2. Verify that the Client Protocol is openid-connect.
  3. Change Access Type to confidential.
  4. Toggle Direct Access Grants Enabled to OFF.
  5. Enter a Valid Redirect URL (e.g. https://dex-companyname.cognitivescale.gke.insights.ai/callback).
  6. Toggle Authorization Enabled to ON.
  7. Click Save at the bottom of the tab.

keycloak-client-settings

Step 2: Set up User Realm Roles or Client Roles

Option 2a: Set up User Realm Roles

Realm-level roles are a global namespace to define your roles. You can see the list of built-in and created roles by clicking the Roles left menu item.

  1. In the Keycloak Admin Console click Roles in the left panel.
  2. Click Add Role on the role list page.
  3. Enter the Role name and description.
  4. Click Save.

keycloak-add-role

Option 2b: Set up Client Roles

Client roles are basically a namespace dedicated to a client. Each client gets its own namespace. Client roles are managed under the Roles tab under each individual client. You interact with this UI the same way you do for realm-level roles.

  1. In the Keycloak Admin Console click Clients in the left panel.
  2. Click the name of a Client to open the details tabs.
  3. Open the Roles tab.
  4. Enter the Role name and description.
  5. Click Save.

Step 3 (Optional): Set up Groups

Groups in Keycloak allow you to manage a common set of attributes and role mappings for a set of users. Users can be members of zero or more groups. Users inherit the attributes and role mappings assigned to each group.

  1. In the Keycloak Admin Console click Groups in the left panel.

  2. Click New.

    keycloak-groups

  3. Enter Groups in a hierarchical order.

    Subgroups inherit the attributes and role mappings from the parent. This applies to the user as well. So, if you have a parent group and a child group and a user that only belongs to the child group, the user inherits the attributes and role mappings of both the parent and child.

  4. Give the group a Name.

  5. Click Save.

keycloak-create-group

Step 4: Add a User

  1. Click Users in the left panel.
  2. Click Add User on the user list page.
  3. Enter username, email, first name and last name of the user. (NOTE: Email format is not verified.)
  4. Click Save

keycloak-add-user

  1. Open the “Credentials” tab.
  2. Enter New Password and Password Confirmation for the user.
  3. Click Set Password.

keycloak-set-password

Step 5: Set up Client Scope for Groups

Keycloak allows you to define a shared client configuration in an entity called a Client Scope. Client Scopes also provide support for the OAuth 2 scope parameter, which allows a client application to request more or fewer claims or roles in the access token, according to the application needs.

  1. From the Client details open the Client Scopes tab.
  2. Click Create at the top right of the list.
  3. Set the assigned default client scopes to email and profile.

keycloak-client-scope

Step 6: User Role mappings

  1. Click Users in the left panel.
  2. Click a user name in the user list.
  3. Open the Role Mappings tab.
  4. Click on the role you created under Available Role to select it.
  5. Click Add Selected to move the role to Assigned Roles.

keycloak-map-roles

Step 7: Restrict Access to a Role

To restrict Certifai access to a role, a protocol mapper needs to be defined that adds the user's roles to the ID token.

  1. In the Keycloak Admin Console click Clients in the left panel.
  2. Select a client from the list to open the details tabs.
  3. Open the Mappers tab.
  4. Click Create at the top right of the list.
  5. Enter a name for the mapper record.
  6. Select the Mapper Type of (User Realm Role, Client Role, or Groups).
  7. Toggle Multivalued to ON.
  8. Enter groups as the Token Claim Name.
  9. Select Claim JSON Type - string.
  10. Toggle Add to ID Token to ON.
  11. Click Save

keycloak-client-mappers

Step 8: Evaluate User Access

The goal of the Evaluation step is to verify that a user is given access to Certifai (on Keycloak). To have access the user must have an email address that has been verified.

  1. In the Keycloak Admin Console click Clients in the left panel.
  2. Select a Clients from the list to open the details tabs.
  3. Open the Client Scopes tab (at the top).
  4. Open the Evaluate sub-tab (under the top layer of tabs).
  5. Select the Scope Parameter you want to evaluate. (You should evaluate email and profile parameters.)
  6. Select the user that you want to evaluate for the parameter.
  7. Click Evaluate.
  8. In the results panel below open the Generated Access Token tab.
  9. Verify that the properties email and email_verified:true are displayed in the output panel.

keycloak-evaluate-user-access

Test Keycloak Setup

Keycloak implements SSO and will authenticate the user automatically with the credentials they last used to log in to any Keycloak application (subject to expiry).

For example, if you are logged into the Keycloak Admin Console when you try to reach the Certifai Console, the same credentials are used.

While testing your setup, you should to use a separate browser for testing Certifai sign on. (e.g. Guest in Chrome)

To test, enter the URL for the Certifai Console in your browser window. You are redirected to Keycloak to authenticate.

Login Troubleshooting

  • If the email is not registered in Keycloak, a Bad Gateway or Service Temporarily Unavailable error message is displayed.
  • If you have logged in previously and received an authorization error, clear the cookie associated with the Certifai Console and try again.
  • If you have logged into Keycloak and changed user, client, or group settings (e.g. scopes, roles, mappers), log out of Keycloak to ensure that new credentials are issued.
  • If the message Unable to verify ID token is displayed, restart the Certifai Console by deleting the Certifai Console pod in Kubernetes.