---
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

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
    > :width: 70%
    >
    > **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
    > :width: 70%
    >
    > **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
    > :width: 70%
    >
    > **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
    > :width: 70%
    >
    > **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
    > :width: 70%
    >
    > **Mappers**
    > ```

### Kasm OpenID Config

1. Log into the Kasm UI as an administrator.

2. Select **Authentication** -> **OpenID** -> **Create New Configuration**.

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.png
   > :align: center
   > :width: 70%
   >
   > **Kasm OIDC Configurations**
   > ```

6) Click **Submit** 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.png
   > :align: center
   > :width: 50%
   >
   > **Login Screen**
   > ```

2. Click **Continue with Keycloak**

3. The user is redirected to Keycloak for auth.

   > ```{figure} /images/oidc/keycloak/authorization.png
   > :align: center
   > :width: 90%
   >
   > **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 **Groups** -> **Add Group**.
3. Name the Group **Group Test**, and define a priority.
4. Click **Submit** to create the group.

> ```{figure} /images/oidc/keycloak/groups.png
> :align: center
> :width: 90%
>
> **Group Configuration**
> ```

1. On the groups screen, using the three dot menu select **View** on the group that was just created.
2. Scroll to the bottom of the screen and select **Add SSO Mapping**.
3. Select the OpenID IDP that was created above "OpenID - Continue with Keycloak" for the **SSO Provider**.

#. 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 **Add**

> ```{figure} /images/oidc/keycloak/sso_group_mapping.png
> :align: center
> :width: 90%
>
> **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.