From 078b8d0313ac1714b2165f691b6fc07e8d9ba482 Mon Sep 17 00:00:00 2001
From: pollfly <75068813+pollfly@users.noreply.github.com>
Date: Wed, 26 Feb 2025 13:39:15 +0200
Subject: [PATCH] Add Multi-Tenant Login Mode (#1054)

---
 .../sso_multi_tenant_login.md                 | 98 +++++++++++++++++++
 sidebars.js                                   |  1 +
 2 files changed, 99 insertions(+)
 create mode 100644 docs/deploying_clearml/enterprise_deploy/sso_multi_tenant_login.md

diff --git a/docs/deploying_clearml/enterprise_deploy/sso_multi_tenant_login.md b/docs/deploying_clearml/enterprise_deploy/sso_multi_tenant_login.md
new file mode 100644
index 00000000..b1508c4f
--- /dev/null
+++ b/docs/deploying_clearml/enterprise_deploy/sso_multi_tenant_login.md
@@ -0,0 +1,98 @@
+---
+title: Multi-Tenant Login Mode
+---
+
+In a multi-tenant setup, each external tenant can be represented by an SSO client defined in the customer Identity provider 
+(Keycloak). Each ClearML tenant can be associated with a particular external tenant. Currently, only one 
+ClearML tenant can be associated with a particular external tenant
+
+## Setup IdP/SSO Client in Identity Provider
+
+1. Add the following URL to "Valid redirect URIs": `<clearml_webapp_address>/callback_<client_id>`  
+2. Add the following URLs to "Valid post logout redirect URIs": 
+
+   ```
+   <clearml_webapp_address>/login
+   <clearml_webapp_address>/login/<external tenant ID>
+   ```
+3. Make sure the external tenant ID and groups are returned as claims for a each user
+
+## Configure ClearML to use Multi-Tenant Mode
+
+Set the following environment variables in the ClearML enterprise helm chart under the `apiserver` section:  
+* To turn on the multi-tenant login mode:
+
+  ```
+  - name: CLEARML__services__login__sso__tenant_login
+    value: "true"
+  ```
+* To hide any global IdP/SSO configuration that's not associated with a specific ClearML tenant:  
+
+  ```
+  - name: CLEARML__services__login__sso__allow_settings_providers
+    value: "false"
+  ```
+  
+Enable `onlyPasswordLogin` by setting the following environment variable in the helm chart under the `webserver` section:
+
+``` 
+- name: WEBSERVER__onlyPasswordLogin`  
+  value: “true”`
+```
+
+## Setup IdP for a ClearML Tenant
+
+To set an IdP client for a ClearML tenant, you’ll need to set the ClearML tenant settings and define an identity provider:
+
+1. Call the following API to set the ClearML tenant settings:
+
+   ```
+   curl $APISERVER_URL/system.update_company_sso_config -H "Content-Type: application/json" -u $APISERVER_KEY:$APISERVER_SECRET -d'{  
+     "company": "<company_id>",  
+     "sso": {  
+       "tenant": "<external tenant ID>",  
+       "group_mapping": {  
+         "IDP group name1": "Clearml group name1",  
+         "IDP group name2": "Clearml group name2"  
+       },  
+       "admin_groups": ["IDP admin group name1", "IDP admin group name2"]  
+     }}'  
+   ```
+2. Call the following API to define the ClearML tenant identity provider:
+
+   ```
+   curl $APISERVER_URL/sso.save_provider_configuration -H "Content-Type: application/json" -u $APISERVER_KEY:$APISERVER_SECRET -d'{  
+     "provider": "keycloak", 
+     "company": "<company_id>",  
+     "configuration": {  
+       "id": "<some unique id here, you can use company_id>",  
+       "display_name": "<The text that you want to see on the login button>",  
+       "client_id": "<client_id from IDP>",  
+       "client_secret": "<client secret from IDP>",  
+       "authorization_endpoint": "<authorization_endpoint from IDP OpenID configuration>",  
+       "token_endpoint": "<token_endpoint from IDP OpenID configuration>",  
+       "revocation_endpoint": "<revocation_endpoint from IDP OpenID configuration>",  
+       "end_session_endpoint": "<end_session_endpoint from IDP OpenID configuration>",  
+       "logout_from_provider": true,  
+       "claim_tenant": "tenant_key",  
+       "claim_name": "name",  
+       "group_enabled": true,  
+       "claim_groups": "ad_groups_trusted",  
+       "group_prohibit_user_login_if_not_in_group": true  
+     }}'  
+   ```
+   The above configuration assumes the following:  
+   * On logout from ClearML, the user is also logged out from the Identity Provider  
+   * External tenant ID for the user is returned under the `tenant_key` claim  
+   * User display name is returned under the `name` claim  
+   * User groups list is returned under the `ad_groups_trusted` claim  
+   * Group integration is turned on and a user will be allowed to log in if any of the groups s/he belongs to in the 
+     IdP exists under the corresponding ClearML tenant (this is after group name translation is done according to the ClearML tenant settings)
+
+## Webapp Login
+
+When running in multi-tenant login mode, a user belonging to some external tenant should use the following link to log in:  
+
+```
+<clearml_webapp_address>/login/<external tenant ID>
+```
\ No newline at end of file
diff --git a/sidebars.js b/sidebars.js
index d2931746..2843c553 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -671,6 +671,7 @@ module.exports = {
                     label: 'Identity Provider Integration',
                     link: {type: 'doc', id: 'user_management/identity_providers'},
                     items: [
+                        'deploying_clearml/enterprise_deploy/sso_multi_tenant_login',
                         'deploying_clearml/enterprise_deploy/sso_saml_k8s',
                         'deploying_clearml/enterprise_deploy/sso_keycloak',
                         'deploying_clearml/enterprise_deploy/sso_active_directory'