clearml-docs/docs/deploying_clearml/enterprise_deploy/sso_keycloak.md

title
KeyCloak IdP Configuration

This procedure is a step-by-step guide of the configuration process for the ClearML Enterprise Server with the KeyCloak IdP.

In the following sections, the term "publicly accessible" does not have to mean open to the entire world or publicly accessible from the Internet, it simply means accessible to your users from their workstations (typically when using a browser).

In the following sections, you will be instructed to set up different environment variables for the ClearML Server. If using a docker-compose deployment, these should be defined in your docker-compose.override.yaml file, under the apiserver service’ environment variables, as follows:

services:
  ...
  apiserver:
    ...
    environment:
      <name>=<value>
      ...

If using a Kubernetes deployment, these should be set in the ClearML Enterprise server chart values override file, under the .Values.apiserver.extraEnvs array section, as follows:

...
apiserver:
  extraEnvs:
    - name: <name>
      value: "<value>"
    - ...

All examples below are provided in the Kubernetes format.

Prerequisites

• An existing ClearML Enterprise server / control-plane installation (using docker-compose or Kubernetes), which is set up with a publicly accessible endpoint fo the ClearML WebApp
• A KeyCloak IdP installed with a publicly accessible endpoint, with you as admin having access to the KeyCloak administration UI.

Configuration

Basic Setup

KeyCloak Configuration

In the KeyCloak administration UI:

1. Register a new ClearML app with the callback url: <ClearML_webapp_address>/callback_keycloak
2. Make sure that the claims representing user_id, email and user name are returned
3. Make a note of the client_id, client_secret, Auth url and Access token url for configuration in the ClearML Server.

ClearML Server Configuration

In the ClearML Server deployment, set the environment variables specified below.

KeyCloak Base URL

Use the start of the token or authorization endpoint, usually the part just before protocol/openid-connect/...

- name: CLEARML__services__login__sso__oauth_client__keycloak__base_url
  value: "<base url>"

KeyCloak Authorization Endpoint

- name: CLEARML__services__login__sso__oauth_client__keycloak__authorize_url
  value: "<authorization endpoint>"

KeyCloak Access Token Endpoint

- name: CLEARML__services__login__sso__oauth_client__keycloak__access_token_url
  value: "<token endpoint>"

KeyCloak Client ID

The client ID is obtained when creating the KeyCloak ClearML App.

- name: CLEARML__secure__login__sso__oauth_client__keycloak__client_id
  value: "<clinet_id>"

KeyCloak Client Secret

The client secret is obtained when creating the KeyCloak ClearML App.

- name: CLEARML__secure__login__sso__oauth_client__keycloak__client_secret
  value: "<client_secret>"

Automatic User Creation Support

Usually, when using IdPs in ClearML, the ClearML Server will map users signing in to the server into tenants (companies) using predefined whitelists and specific invitations (users explicitly added by admins).

To support automatic user creation in a trusted environment, where all users signing in using this IdP are automatically added to the same tenant (company), the following environment variable should be set:

- name: CLEARML__secure__login__sso__oauth_client__keycloak__default_company
  value: "<company_id>"

User Groups Integration

This option allows automatically synchronizing group membership from KeyCloak into existing ClearML User Groups when logging in users (this is done on every user login, not just on user sign-in).

Make sure a ClearML User Group exists for each potential KeyCloak group that should be synchronized to prevent an uncontrolled proliferation of user groups. The ClearML server will not automatically create user groups in this mode.

Keycloak Configuration

• When configuring the Open ID client for ClearML:
  • Navigate to the Client Scopes tab
  • Click on the first row <clearml client>-dedicated
  • Click Add Mapper → By configuration and then select the Group membership option
  • In the opened dialog enter the name groups and Token claim name groups
  • Uncheck the Full group path option and save the mapper
• To validate yourself:
  • Return to the Client Details → Client scope tab
  • Go to the Evaluate sub-tab and select a user that has any group memberships
  • On the right side navigate to Generated ID token and then to Generated User Info
  • Inspect that in both cases you can see the groups claim in the displayed user data

ClearML Server Configuration

Set the following environment variables for the apiserver service:

- name: CLEARML__services__login__sso__oauth_client__keycloak__groups__enabled
  value: "true"
- name: CLEARML__services__login__sso__oauth_client__keycloak__groups__claim
  value: "groups"
- name: CLEARML__services__login__sso__oauth_client__keycloak__claims__name
  value: "preferred_username"

Setting Administrators by Group Association

In case you would like the members of the particular KeyCloak group to be set as administrators in ClearML, set the following environment variable. Note that in this case, the KeyCloak group(s) do not have to be present in the ClearML Server.

- name: CLEARML__services__login__sso__oauth_client__keycloak__groups__admins
  value: "[\"<the name of admin group from Keycloak>\"]"

Restrict User Signup

To prevent sign in for users who do not have a matching group(s) found using the above-mentioned configuration, set the following environment variable.

- name: CLEARML__services__login__sso__oauth_client__keycloak__groups__prohibit_user_signup_if_not_in_group
  value: "true"

Administrator User Role Association

For integration of an admin user role from KeyCloak into the ClearML service, do the following.

KeyCloak Configuration

1. For each administrator user, assign the admin role to that user in KeyCloak
2. In the Client Scopes tab, make sure that the roles claim is returned in the access token or userinfo token (this depends on the configuration in step 1)

ClearML Server Configuration

By default, the ClearML Server will use the admin claim to identify administrator users. To use a different group name for designating the admin role, set the following environment variable:

- name: CLEARML__services__login__sso__oauth_client__keycloak__admin_role
  value: "<admin claim name>"

Disabling Admin Role Association

To disable the automatic administrator claim and manage administrators solely from inside the ClearML WebApp, make sure that user roles are not returned by KeyCloak in the auth token or the userinfo endpoint, and/or set the following ClearML Server environment variable:

- name: CLEARML__services__login__sso__oauth_client__keycloak__admin_role
  value: ""

Additional ClearML Server Configurations

KeyCloak Session Logout

To automatically log out the user from the KeyCloak provider when the user logs out of the ClearMK service, set the following environment variable. This will make sure that the KeyCloak session is not maintained in the browser so that when the user tries to log into the ClearML service, the KeyCloak login page will be used again and not skipped.

- name: CLEARML__services__login__sso__oauth_client__keycloak__idp_logout
  value: "true"

User Info Source

By default, the user info is taken from the KeyCloak access token. If you prefer to use the user info available through the OAuth’s protocol userinfo endpoint, set the following environment variable:

- name: CLEARML__services__login__sso__oauth_client__keycloak__get_info_from_access_token
  value: "false"