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

## Auth0 OpenID Setup

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

Reference Docs:

- <https://auth0.com/docs/authenticate/protocols/openid-connect-protocol>

- <https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes>

### Creating an Auth0 OAuth App

01. Login to the Auth0 portal as an Admin.

02. Expand **Authentication** and select **Applications**.

03. Click **Create Application**.

```{figure} /images/oidc/auth0/create_application.png
:align: center
**Create Application**
```

04. Give the app a name (e.g `Kasm OIDC`), select **Regular Web Application** and click **Create**.

```{figure} /images/oidc/auth0/create_web_application.png
:align: center
**Create Web Application**
```

05. Select the **Settings** Tab.

06. Take note of the **Client ID** and **Client Secret** values. These will be used in later steps.

```{figure} /images/oidc/auth0/client_id.png
:align: center
**Create ID and Secret**
```


07. In the **Application URIs** section enter `https://<kasm-deployment>/api/oidc_callback`. For example (`https://kasm.example.com/api/oidc_callback`).
    
```{figure} /images/oidc/auth0/application_uris.png
:align: center
**Callback URI**
```

08. Scroll down and expand **Advanced Settings**, the select **Endpoints**. Take note of the **OAuth Authorization URL**, **OAuth Token URL**, and 
**OAuth User Info URL**. These will be used in later steps.

```{figure} /images/oidc/auth0/endpoints.png
:align: center
**OAuth Endpoints**
```

09. Click **Save Changes**.


### (Optional) Configuring Auth0 to forward User Roles

In many cases it may be desireable to place SSO users in specific Kasm Groups based on their Roles as defined within
Auth0. The following steps may be used to configure Auth0 to provide Kasm with the User's Role during authentication.


01. From the Auth0 admin console expand **Actions**, select **Library** and click **Build Custom**.


```{figure} /images/oidc/auth0/build_custom.png
:align: center
**Build Custom Action**
```

02. In the Create Action popup, enter a name (e.g `Add User Roles`) , select `Login / Post Login` as the **Trigger** and the recommended runtime (e.g `Node 18 Recommended`).

```{figure} /images/oidc/auth0/create_action.png
:align: center
**Create Action**
```

03. Click **Create**.
    
04. Replace the contents of editor with the following code snippet and click **Deploy** .

```Javascript
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'auth0';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}
```

```{figure} /images/oidc/auth0/deploy_action.png
:align: center
**Deploy Action**
```

```{note}
This example is pulled from the Auth0 Documentation:
https://auth0.com/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#add-user-roles-to-tokens

The `namespace` can be changed as desired. Per the example `auth0` is used which will result in the 
**Groups Attrbute** setting in the Kasm OIDC config being `auth0/roles`.
```

05. In the main menu, expand **Actions**, select **Flows**, then click **Login**.


```{figure} /images/oidc/auth0/login_flow.png
:align: center
**Login Flow**
```


06. In the **Add Action** section, select **Custom**. The recently created action (e.g `Add User Roles`) should be visible.

```{figure} /images/oidc/auth0/configure_login_flow_1.png
:align: center
**Login Flow**
```

07. Drag the action into the workflow and click **Apply**.


```{figure} /images/oidc/auth0/configure_login_flow_2.png
:align: center
**Login Flow**
```


### 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 Auth0                                                            |
+------------------------+--------------------------------------------------------------------------------+
| **Logo URL**           | :code:`https://cdn.auth0.com/website/new-homepage/dark-favicon.png`            |
+------------------------+--------------------------------------------------------------------------------+
| **Enabled**            | Checked                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Auto Login**         | Unchecked                                                                      |
+------------------------+--------------------------------------------------------------------------------+
| **Hostname**           | <Empty>                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Default**            | Checked                                                                        |
+------------------------+--------------------------------------------------------------------------------+
| **Client ID**          | <Client ID from Auth0>                                                         |
+------------------------+--------------------------------------------------------------------------------+
| **Client Secret**      | <Client Secret from Auth0>                                                     |
+------------------------+--------------------------------------------------------------------------------+
| **Authorization URL**  | <OAuth Authorization URL from the Auth0 configuration>                         |
+------------------------+--------------------------------------------------------------------------------+
| **Token URL**          | <OAuth Token URL from the Auth0 configuration>                                 |
+------------------------+--------------------------------------------------------------------------------+
| **User Info URL**      | <OAuth User Info URL from the Auth0 configuration>                             |
+------------------------+--------------------------------------------------------------------------------+
| **Scope**              | :code:`openid`                                                                 |
|                        | :code:`email`                                                                  |
|                        | :code:`profile`                                                                |
+------------------------+--------------------------------------------------------------------------------+
| **Username Attribute** | :code:`email`                                                                  |
+------------------------+--------------------------------------------------------------------------------+
| **Groups Attribute**   | :code:`auth0/roles`                                                            |
+------------------------+--------------------------------------------------------------------------------+
| **Debug**              | Unchecked                                                                      |
+------------------------+--------------------------------------------------------------------------------+
```

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

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

### Auth0 Login Test

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

```{figure} /images/oidc/auth0/login.png
:align: center
**Login Screen**
```

2. Click **Continue with Auth0**

3. The user is redirected to Auth0 for auth.

```{figure} /images/oidc/auth0/authorization.png
:align: center
**Auth0 Auth**
```

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

### Group Mapping

In a previous section Auth0 was configured to send a list of **Roles** the user belongs to during
the OpenID auth workflow. We can now configure Kasm Groups with the Role associations so that
users are automatically added/removed based on their Auth0 Membership.

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

```{figure} /images/oidc/auth0/groups.png
: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 Auth0` for the **SSO Provider**.
4. Then enter the Auth0 group name desired in the **Group Attributes** field, e.g {code}`Kasm Premium`.
5. Click **Submit**

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

The Example Role as defined in Auth0.
```{figure} /images/oidc/auth0/sso_role_config.png
:align: center
**Auth0 Role SSO**
```


1. Logout, then login via the Auth0 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.