---
myst:
  html_meta:
    "description lang=en": "Keycloak OpenID setup guide for Workspaces authentication."
    "keywords": "Kasm, Keycloak, OpenID, OIDC"
    "property=og:locale": "en_US"
---
```{title} Keycloak OpenID Setup
```

## Keycloak OpenID Setup

```{include} /guide/oidc/warning.md
```

This guide walks through a basic setup allowing Keycloak users to authenticate with your Kasm deployment.

Reference Docs:

- <https://www.keycloak.org/docs/latest/securing_apps/#_oidc>

### Creating a Keycloak OAuth App

01. Login to the Keycloak portal as an Admin.

02. Under the the desired realm (e.g **Master**) , select **Realm Settings**.

03. Click **OpenID Endpoint Configuration** next to Endpoints.

```{figure} /images/oidc/keycloak/realm_settings.png
:align: center
**Realm Settings**
```

04. Save off the urls for {code}`authorization_endpoint` , {code}`token_endpoint`, and {code}`userinfo_endpoint`.
    These will be used in future steps.

```{figure} /images/oidc/keycloak/endpoints.png
:align: center
**Keycloak Endpoints**
```

05. Back in the console, select **Clients** under the Realm.

06. Select **Create**.

07. Define a **Client ID** , e.g {code}`kasm-12345`. Select {code}`openid-connect` for **Client Protocol** and enter the URL for
    the Kasm deployment under **Root URL** (e.g {code}`https://kasm.example.com`).

```{figure} /images/oidc/keycloak/add_client.png
:align: center
**Add Client**
```

08. In the client settings, change **Access Type** to {code}`confidential`, then slick **Save**.

09. Select **Credentials**. Save off the **Secret**. It will be used in future steps.

```{figure} /images/oidc/keycloak/secret.png
:align: center
**Client Secret**
```

10. In the client settings, select **Mappers**, then click **Create**.

11. Enter {code}`groups` for **Name**, and select **Group Membership** from the Mapper Type. Enter {code}`groups` for
    **Token Claim Name**, then select **Save**.

```{figure} /images/oidc/keycloak/mapper.png
:align: center
**Mappers**
```

### Kasm OpenID Config

1. Log into the Kasm UI as an administrator.

2. Select **Access Management** -> **Authentication** -> **OpenID** -> **Add Config**.

3. Update the form with the following entries, using the **Client ID** and **Client Secret** gathered in the previous section.

```{eval-rst}
+------------------------+--------------------------------------------------------------------------------+
| **Property**           | **Value**                                                                      |
+------------------------+--------------------------------------------------------------------------------+
| **Display Name**       | Continue with Keycloak                                                         |
+------------------------+--------------------------------------------------------------------------------+
| **Logo URL**           | :code:`http://www.keycloak.org/resources/favicon.ico`                          |
+------------------------+--------------------------------------------------------------------------------+
| **Enabled**            | Checked                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Auto Login**         | Unchecked                                                                      |
+------------------------+--------------------------------------------------------------------------------+
| **Hostname**           | <Empty>                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Default**            | Checked                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Client ID**          | <Client ID from Keycloak>                                                      |
+------------------------+--------------------------------------------------------------------------------+
| **Client Secret**      | <Client Secret from Keycloak>                                                  |
+------------------------+--------------------------------------------------------------------------------+
| **Authorization URL**  | <authorization_endpoint from the Keycloak configuration>                       |
+------------------------+--------------------------------------------------------------------------------+
| **Token URL**          | <token_endpoint from the Keycloak configuration>                               |
+------------------------+--------------------------------------------------------------------------------+
| **User Info URL**      | <userinfo_endpoint from the Keycloak configuration>                            |
+------------------------+--------------------------------------------------------------------------------+
| **Scope**              | :code:`openid`                                                                 |
|                        | :code:`email`                                                                  |
|                        | :code:`profile`                                                                |
+------------------------+--------------------------------------------------------------------------------+
| **Username Attribute** | :code:`preferred_username`                                                     |
+------------------------+--------------------------------------------------------------------------------+
| **Groups Attribute**   | :code:`groups`                                                                 |
+------------------------+--------------------------------------------------------------------------------+
| **Debug**              | Unchecked                                                                      |
+------------------------+--------------------------------------------------------------------------------+
```

```{figure} /images/oidc/keycloak/kasm_oidc_configuration.webp
:align: center
**Kasm OIDC Configurations**
```

6) Click **Save** to save the changes.

### Keycloak Login Test

1. Logout of the Kasm to display the login screen. The OpenID configuration should be shown.

```{figure} /images/oidc/keycloak/login.webp
:align: center
**Login Screen**
```

2. Click **Continue with Keycloak**

3. The user is redirected to Keycloak for auth.

```{figure} /images/oidc/keycloak/authorization.png
:align: center
**Keycloak Auth**
```

4. Upon completion, the user is logged into the Kasm app.

### Group Mapping

The previous configurations will instruct the identity provider to send a list of **Security Group ID** the user belongs to during
the OpenID auth workflow. We can configure Kasm Groups with the Security Group IDs from Azure AD so that users are automatically added/removed
based on their Azure AD group Membership.

1. Log into the Kasm UI as an administrator.
2. Select **Access Management** -> **Groups** -> **Add Group**.
3. Name the Group **Group Test**, and define a priority.
4. Click **Save** to create the group.

```{figure} /images/oidc/keycloak/groups.webp
:align: center
**Group Configuration**
```

1. On the groups screen, using the arrow menu select **Edit** on the group that was just created.
2. Navigate to the **SSO Group Mappings** tab and select **Add SSO Mapping**.
3. Select the OpenID IDP that was created above "OpenID - Continue with Keycloak" for the **SSO Provider**.
4. Then enter the Keycloak group name desired in the **Group Attributes** field, e.g {code}`/Kasm-Test`.
Note the slash. This is needed when **Full group path** is set in the Keycloak Client Mapper which is the default.

1. Click **Submit**

```{figure} /images/oidc/keycloak/sso_group_mapping.webp
:align: center
**Add SSO Group Mapping**
```

1. Logout, then login via the Keycloak Open ID login with a user that is a member of the specified group.
2. View the users group membership to ensure they are added to the newly created group.