---
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 `master`) 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** | **Kasm 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, ensure **Want Attribute Statement**, **Want Assertions Signed**, and **Want Name ID** are enabled.
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 `master`) then select Clients.
```{figure} /images/saml/keycloak/clients.png
:align: center
**Keycloak Portal**
```
2. In the Clients window select **Create Client**.
3. In the **Client type** select **SAML**
4. In the **Client ID** enter a short name (e.g `kasm`) - Note: we will modify this in the next section to work around a keycloak bug.
5. Enter a value for the **Name** field (e.g Kasm Workspaces).
6. Select **Next**.
```{figure} /images/saml/keycloak/add_client.png
:align: center
**Add Client**
```
7. Update the **Home URL** with the URL of the Workspaces deployment (e.g {code}`https://my.kasm.server`).
8. Update **Valid Redirect URLs** with a wildcard entry for the Workspaces deployment (e.g {code}`https://my.kasm.server/*`
9. Select **Save**.
```{figure} /images/saml/keycloak/add_client2.png
:align: center
**Add Client**
```
### Client Configurations
Update the client details configuration
1. In the Client Details page, select the **Settings** tab.
2. In the **Client ID** field, enter the value found in the **Entity ID** from the **Service Provider** sections in the Workspaces SAML configuration form.
3. In the **Master SAML Processing URL** enter the value found in the **Single Sign On Service** from the **Service Provider** sections in the Workspaces SAML configuration form.
4. Ensure **Name ID format** is `username`.
5. Ensure **Force name ID format** is set to **On**.
6. Ensure **Sign Assertions** is set to **On**.
7. Click **Save**
```{figure} /images/saml/keycloak/client_configs.png
:align: center
**Client Settings**
```
8. Select the **Keys** tab.
9. Set **Client signature required** to **Off**
```{figure} /images/saml/keycloak/client_signature.png
:align: center
**Keys**
```
10. Select the **Advanced** Tab.
11. In the **Logout Service POST Binding URL** enter the value found in the **Single Logout Service** from the **Service Provider** sections in the Workspaces SAML configuration form.
12. Click **Save**
```{figure} /images/saml/keycloak/client_advanced.png
:align: center
**Advanced**
```
### Adjust Single Role Attribute in Keycloak
1. Navigate to the Keycloak Admin Portal. Select the desired Realm (e.g `master`) 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 `master`) then select **Realm Roles**.
```{figure} /images/saml/keycloak/roles.png
:align: center
**Keycloak Portal**
```
2. Select **Create 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 username for the desired user.
```{figure} /images/saml/keycloak/user_selection.png
:align: center
**User Selection**
```
05. Select the **Role Mappings** tab, then select **Assign role**
06. Select **kasm_admins** from the **Available Roles** then click **Assign**.
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**
```
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.