---
myst:
html_meta:
"description lang=en": "Keycloak SAML setup guide for Workspaces authentication."
"keywords": "Kasm, Keycloak, SAML"
"property=og:locale": "en_US"
---
```{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 **Access Management** -> **Authentication** -> **SAML** -> **Add 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.webp
:align: center
**Kasm SAML Configurations**
```
09. 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
:align: center
**Realm Settings**
```
3. Copy the following items from the XML document to the **Identity Provider** section of the SAML configuration in Workspaces.
```{eval-rst}
+--------------------------------------------+--------------------------------------------+
| **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
: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 **Save**.
```{figure} /images/saml/keycloak/kasm_idp_configs.webp
: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
: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
: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
: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**.
```{eval-rst}
+---------------------------------+--------------------------------------------+
| **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
: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
: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
: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.webp
:align: center
**Kasm Login**
```
3. Click **Keycloak** to initiate the SAML SSO process.
```{figure} /images/saml/keycloak/keycloak_login.png
: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
:align: center
**Keycloak Portal**
```
2. Select **Add Role**.
3. Name the role **kasm_admins** then click **Save**.
```{figure} /images/saml/keycloak/create_role.png
: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
:align: center
**User Selection**
```
05. Select the **Role Mappings** tab.
06. Select **kasm_admins** from the **Available Roles** then click **Add selected**.
07. Log into the Kasm UI as an administrator.
08. Select **Access Management** -> **Groups**, then click **Add Group**.
09. Name the Group **Keycloak Kasm Admins** and give it a priority (e.g 10).
10. Save the new group by clicking **Save**.
```{figure} /images/saml/keycloak/create_group.webp
:align: center
**Create Group**
```
11. On the **Groups** screen, using the arrow menu select **Edit** on the group that was just created.
12. Navigate to the **SSO Group Mappings** tab 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 **Submit**.
```{figure} /images/saml/keycloak/create_sso_group_mapping.webp
:align: center
**Add SSO Group Mapping**
```
12. Using the arrow menu select **Edit** next to the **Keycloak Kasm Admins** Group.
13. Click **Add Settings** in the **Settings** section.
14. Select **administrator** from the dropdown , select **True**, then **Submit**.
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.