diff --git a/docs/deploying_clearml/enterprise_deploy/sso_keycloak.md b/docs/deploying_clearml/enterprise_deploy/sso_keycloak.md new file mode 100644 index 00000000..4462e1af --- /dev/null +++ b/docs/deploying_clearml/enterprise_deploy/sso_keycloak.md @@ -0,0 +1,225 @@ +--- +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: + = + ... +``` + +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: + 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: `/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: "" +``` + +##### KeyCloak Authorization Endpoint + +``` +- name: CLEARML__services__login__sso__oauth_client__keycloak__authorize_url + value: "" +``` + +##### KeyCloak Access Token Endpoint + +``` +- name: CLEARML__services__login__sso__oauth_client__keycloak__access_token_url + value: "" +``` + +##### 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: "" +``` + +##### 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: "" +``` + +##### 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: "" +``` + +### 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 `-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: "[\"\"]" +``` + +##### 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: "" +``` + +#### 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" +``` + diff --git a/sidebars.js b/sidebars.js index 29c4e5a4..a4e7bccf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -709,6 +709,7 @@ module.exports = { { 'SSO': [ 'deploying_clearml/enterprise_deploy/sso_saml_k8s', + 'deploying_clearml/enterprise_deploy/sso_keycloak', ] }, ]