Setup Keycloak for Console

Prerequisites

• Access to Keycloak Master Realm

note

SmoothGlue can automatically configure this client and group out of the box. Please see the SmoothGlue auto-SSO feature. Skip to Create Console-Bot Admin User if not manually setting up the Keycloak client and group.

Create Keycloak Client

1. In the smoothglue realm, click on Clients under Manage in the left pane.
2. Click Create client.
3. Ensure the Client type is OpenId Connect.
4. Enter a unique client name (e.g., console) for Client ID.
5. Click on the Next button.
6. Ensure Client authentication is toggled on, Standard flow is enabled, and Direct access grants is disabled
7. Click on the Next button.
8. Set Valid Redirect URIs to https://console.${DOMAIN}/login/generic_oauth.
9. Set Valid post logout redirect URIs to https://console.${DOMAIN}.
10. Click on the Save button.

Configure Dedicated Mapper

1. Go to the console client and click on the Client scopes tab.
2. Click on the console-dedicated client scope.
3. Click Configure a new mapper.
4. Select Group Membership.
5. Enter console-group-membership-mapper for Name,
6. Enter groups for Token Claim Name.
7. Click Save.

Configure _structsureAdmins Group

Console assigns SmoothGlue admins configured in Console to the _structsureAdmins group in Keycloak. It is important that this group has the realm-admin role mapping so that admins can manage users in Keycloak via Console:

1. In the smoothglue realm, click Groups in the left-hand panel.
2. Select _structsureAdmins.
3. Go to Role mapping tab.
4. Click Assign role.
5. Ensure the drop-down filter in the top left is set to Filter by clients.
6. Search for and enable the realm-admin role.
7. Click Assign.

Configure Console for Keycloak

Console uses authservice to get a Java Web Token (JWT) from Keycloak that contains info about the currently logged-in user. Console uses the permissions of the logged-in user to interact with Keycloak APIs to manage user accounts.

If Keycloak is using non-publicly trusted or self-signed certificates, Console will need to be configured with additional CAs in order for Console to talk to Keycloak.

note

The following is automatically configured when using the SmoothGlue auto-SSO feature.

Add the following to bigbang-secrets.yaml:

addons:
  authservice:
    chains:
      console:
        callback_uri: https://console.<DOMAIN>/login/generic_oauth
        match:
          header: :authority
          prefix: console.<DOMAIN>
        client_id: console # the client name created above
        client_secret: <client_secret> # retrieve the client secret from the client's `Credentials` tab in Keycloak
packages:
  console:
    values:
      backend:
        keycloak:
          realm: smoothglue
          host: keycloak.<DOMAIN> # this value can be omitted but is required when setting a custom subdomain for Keycloak.
        caBundle: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

Create Console-Bot Admin User

We recommend starting with an initial Keycloak bot-admin user with the realm-admin role in order to be responsible for downstream tool access tokens. This bot-admin will be used to set up access keys within tools that Console supports integrations for.

caution

Do not log in to Console UI with this user. It is recommended to remove the password for console-bot in Keycloak to reduce the chances of downgrading permissions.

1. In the smoothglue realm, click Users in the left-hand panel.
2. Click Add user.
3. Fill in the following information for the initial user:
   1. Email verified: Enabled
   2. Username: console-bot
   3. Email: console-bot@<your-domain>.com
   4. First name: console
   5. Last name: bot
   6. Groups: _structsureAdmins
4. Click Create.

Set a password for the console-bot user:

1. From the smoothglue realm, go to Users > console-bot.
2. Go to the Credentials tab.
3. Click Set password.
4. Disable Temporary.
5. Enter a password.
6. Click Save and Save password to confirm.

caution

Do not log in to Console UI with this user.