.. title:: Keycloak SAML Setup Keycloak SAML Setup ================================= Create a new SAML configuration in Kasm --------------------------------------- 1. Log into the Kasm UI as an administrator. 2. Select **Authentication** -> **SAML** -> **Create New Configuration** 3. The **SAML 2.0 Configuration** page will auto-generate the **Entity ID**, **Single Sign On Service**, **Single Logout Server**, and **Relay State** values. 4. Check **Enable** and enter a **Display Name**. e.g (Keycloak) 5. Enter the **Hostname** for the workspaces deployment (e.g my.kasm.server). 6. Check **Default**. 7. Enter `Role` in **Group Member Attribute**. 8. Enter `username` in **NameID Attribute**. .. figure:: /images/saml/keycloak/kasm_saml_configuration.png :width: 70% :align: center **Kasm SAML Configurations** 9. Check **Debug**. **Disable this setting after testing is complete**. 10. Leave this page open and continue to the next steps. Realm SAML Settings ------------------- 1. Navigate to the Keycloak Admin Portal. Select the desired Realm (e.g Myrealm) then select Realm Settings. 2. Click on **SAML 2.0 Identity Provider Metadata**. .. figure:: /images/saml/keycloak/realm_settings.png :width: 70% :align: center **Realm Settings** 3. Copy the following items from the XML document to the **Identity Provider** section of the SAML configuration in Workspaces. +--------------------------------------------+--------------------------------------------+ | **Keycloak Property** | **Azure Property Name** | +--------------------------------------------+--------------------------------------------+ | entityID | Entity ID | +--------------------------------------------+--------------------------------------------+ | ds:X509Certificate | X509 Certificate | +--------------------------------------------+--------------------------------------------+ | md:SingleLogoutService..HTTP-POST | Single Logout Service/SLO Endpoint | +--------------------------------------------+--------------------------------------------+ | md:SingleSignOnService..HTTP-POST | Single Sign On Service/SAML 2.0 Endpoint | +--------------------------------------------+--------------------------------------------+ .. figure:: /images/saml/keycloak/keycloak_xml.png :width: 70% :align: center **SAML XML** 4. In the **Advanced Settings** of the Workspaces SAML configuration, check **Want Assertions Signed**. 5. In the **Advanced Settings** of the Workspaces SAML configuration, set **Signature Algorithm** to **rsa-sha256**. 6. Click **Submit**. .. figure:: /images/saml/keycloak/kasm_idp_configs.png :width: 70% :align: center **Identity Provider** 7. Select **Edit** next to the new Saml config as these settings will need to be referenced in th following sections. Add a new client in Keycloak ------------------------------ 1. Navigate to the Keycloak Admin Portal. Select the desired Realm (e.g Myrealm) then select Clients. .. figure:: /images/saml/keycloak/clients.png :width: 70% :align: center **Keycloak Portal** 2. In the Clients window select **Create**. 3. In the **Client ID** field the value found in the **Entity ID** from the **Service Provider** sections in the Workspaces SAML configuration form. 4. Select **saml** as the **Client Protocol** and click **Save**. .. figure:: /images/saml/keycloak/add_client.png :width: 70% :align: center **Add Client** Client Configurations ---------------------- 1. Enter a value for the **Name** field (e.g Kasm Workspaces). 2. Ensure **Sign Assertions** is set to **On**. 3. Ensure **Client Signature Required** is set to **Off**. 4. Ensure **Force Name ID Format** is set to **On**. 5. Update **Valid Redirect URLs** with a wildcard entry for the Workspaces deployment (e.g :code:`https://my.kasm.server/*` ). 6. Update the **Base URL** with the URL of the Workspaces deployment (e.g :code:`https://my.kasm.server`). .. figure:: /images/saml/keycloak/client_configs.png :width: 70% :align: center **Client Configurations** 4. Copy the **Service Provider** entries from the Kasm SAML Configurations started in the previous section into the Basic SAML configurations and click **Save**. +---------------------------------+--------------------------------------------+ | **Keycloak Property** | **Azure Property Name** | +---------------------------------+--------------------------------------------+ | Master SAML Processing URL | Single Sign On Service | +---------------------------------+--------------------------------------------+ | Logout Service POST Binding URL | Single Logout Service | +---------------------------------+--------------------------------------------+ .. figure:: /images/saml/keycloak/saml_url_config.png :width: 70% :align: center **SAML URL Configurations** Adjust Single Role Attribute in Keycloak ----------------------------------------- 1. Navigate to the Keycloak Admin Portal. Select the desired Realm (e.g Myrealm) then select **Client Scopes**. .. figure:: /images/saml/keycloak/client_scopes.png :width: 70% :align: center **Keycloak Portal** 2. Select **role_list** (saml). 3. Select the **Mappers** tab. 4. Select **role list**. 5. Set **Single Role Attribute** to **On**, then click Save. .. figure:: /images/saml/keycloak/role_list.png :width: 70% :align: center **Role List** Testing Access -------------- 1. Log out of the Kasm UI if already logged in. 2. Navigate to the Kasm UI login page. .. figure:: /images/saml/keycloak/kasm_login.png :width: 70% :align: center **Kasm Login** 3. Click **Keycloak** to initiate the SAML SSO process. .. figure:: /images/saml/keycloak/keycloak_login.png :width: 70% :align: center **Keycloak Login** Mapping Roles -------------- During the SAML authentication process , Keycloak will send a list of the user's roles. These can be mapped to Kasm Groups. 1. Navigate to the Keycloak Admin Portal. Select the desired Realm (e.g Myrealm) then select **Roles**. .. figure:: /images/saml/keycloak/roles.png :width: 70% :align: center **Keycloak Portal** 2. Select **Add Role**. 3. Name the role **kasm_admins** then click **Save**. .. figure:: /images/saml/keycloak/create_role.png :width: 70% :align: center **Create Role** 4. Select **Users** from the Keycloak menu, then click the ID next to the desired user. .. figure:: /images/saml/keycloak/user_selection.png :width: 70% :align: center **User Selection** 5. Select the **Role Mappings** tab. 6. Select **kasm_admins** from the **Available Roles** then click **Add selected**. 7. Log into the Kasm UI as an administrator. 8. Select **Groups**, then click **Add Group**. 9. Name the Group **Keycloak Kasm Admins** and give it a priority (e.g 10). 10. Save the new group by clicking **Submit**. .. figure:: /images/saml/keycloak/create_group.png :width: 70% :align: center **Create Group** 11. On the **Groups** screen, using the three dot menu select **View** on the group that was just created. 12. Scroll to the bottom of the screen and select **Add SSO Mapping**. 13. Select the SAML IDP that was created above "SAML - Keycloak" for the **SSO Provider**. 14. Enter **kasm_admins** as the **Group Attributes** then click **Add**. .. figure:: /images/saml/keycloak/create_sso_group_mapping.png :width: 70% :align: center **Add SSO Group Mapping** 12. Using the three dot menu select **View** next to the **Keycloak Kasm Admins** Group. 13. Click **Add Settings** in the **Group Settings** section. 14. Select **administrator** from the dropdown , select **True**, then **Add**. 15. Log out of Kasm, and back in via SAML as the previously assigned user. The user should now be mapped to the **Keycloak Kasm Admins** a group.