---
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}`issuer`, {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. In the **Settings** section, at the bottom, under **Logout**, choose one of the following:
    ```{warning}
    Backchannel Logout is recommended as it is more stable and secure than front-channel.
    Choose front-channel if backchannel is not possible, e.g. keycloak is unable to make a direct HTTPS request to Kasm.
    ```

    01. Front-channel Logout
        - Set **Front-channel logout** to **On**
        - Fill out **Front-channel logout URL** with the endpoint URL for the kasm deployment (e.g. `https://kasm.example.com/api/oidc_frontchannel_logout`)
        - Click **Save**
        ```{figure} /images/oidc/keycloak/slo_frontchannel.png
        :align: center
        **Front-channel SLO**
        ```
        
    02. Backchannel Logout
        - Set **Front channel logout** to **Off**
        - Fill out **Backchannel logout** with the endpoint URL for the kasm deployment (e.g. `https://kasm.example.com/api/oidc_backchannel_logout`)
        - Set **Backchannel logout session required** to **On**
        - Click **Save**
        ```{figure} /images/oidc/keycloak/slo_backchannel.png
        :align: center
        **Backchannel SLO**
        ```

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

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

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

12. 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**                                                         |
+-------------------------------------------+-------------------------------------------------------------------+
| **Enabled**                               | Checked                                                           |
+-------------------------------------------+-------------------------------------------------------------------+
| **Display Name**                          | Continue with Keycloak                                            |
+-------------------------------------------+-------------------------------------------------------------------+
| **Logo URL**                              | :code:`https://www.keycloak.org/resources/favicon.ico`            |
+-------------------------------------------+-------------------------------------------------------------------+
| **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                                                         |
+-------------------------------------------+-------------------------------------------------------------------+
| **Redirect URL**                          | :code:`https://<Kasm hostname>/api/oidc_callback`                 |
+-------------------------------------------+-------------------------------------------------------------------+
| **OpenID Connect Issuer**                 | <issuer from the Keycloak configuration>                          |
+-------------------------------------------+-------------------------------------------------------------------+
| **Logout with OIDC Provider**             | Checked                                                           |
+-------------------------------------------+-------------------------------------------------------------------+
| **Enable OIDC SLO Frontchannel Endpoint** | Checked if Frontchannel Logout was chosen in the previous section |
+-------------------------------------------+-------------------------------------------------------------------+
```

```{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.