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

## Github OpenID Setup

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

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

```{note}
Github OpenID does not support OIDC Single Logout.
```

Reference Docs:

- <https://docs.github.com/en/developers/apps/building-oauth-apps>

### Creating a Github OAuth App

1. Login to Github and select **Settings** from the profile dropdown: <https://github.com/settings/profile>
2. Select **Developer Settings**.
3. Select **OAuth Apps**, then click **New OAuth App**.
4. Give the application a name (e.g {code}`Kasm`), enter the URL of the deployment in the Homepage URL, and the Authorization callback to be {code}`https://<deployment hostname>/api/oidc_callback`.

```{figure} /images/oidc/github/new_oauth_app.png
:align: center
**New OAuth Application**
```

5. Select **Register Application**.
6. On the next page note the **Client ID**. It will be needed for upcoming configurations.
7. Click **Generate a new client secret** and note the value.  It will be needed for upcoming configurations.

```{figure} /images/oidc/github/client_secret.png
:align: center
**Client ID an Client Secret**
```

### 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 Github                                |
+-------------------------------------------+-----------------------------------------------------+
| **Logo URL**                              | :code:`https://github.com/favicon.ico`              |
+-------------------------------------------+-----------------------------------------------------+
| **Auto Login**                            | Unchecked                                           |
+-------------------------------------------+-----------------------------------------------------+
| **Hostname**                              | <Empty>                                             |
+-------------------------------------------+-----------------------------------------------------+
| **Default**                               | Checked                                             |
+-------------------------------------------+-----------------------------------------------------+
| **Client ID**                             | <Client ID From Github OAuth App>                   |
+-------------------------------------------+-----------------------------------------------------+
| **Client Secret**                         | <Client Secret from Github OAuth App>               |
+-------------------------------------------+-----------------------------------------------------+
| **Authorization URL**                     | :code:`https://github.com/login/oauth/authorize`    |
+-------------------------------------------+-----------------------------------------------------+
| **Token URL**                             | :code:`https://github.com/login/oauth/access_token` |
+-------------------------------------------+-----------------------------------------------------+
| **User Info URL**                         | :code:`https://api.github.com/user`                 |
+-------------------------------------------+-----------------------------------------------------+
| **Scope**                                 | :code:`user:email`                                  |
+-------------------------------------------+-----------------------------------------------------+
| **Username Attribute**                    | :code:`email`                                       |
+-------------------------------------------+-----------------------------------------------------+
| **Groups Attribute**                      | <Empty>                                             |
+-------------------------------------------+-----------------------------------------------------+
| **Debug**                                 | Unchecked                                           |
+-------------------------------------------+-----------------------------------------------------+
| **Redirect URL**                          | :code:`https://<Kasm hostname>/api/oidc_callback`   |
+-------------------------------------------+-----------------------------------------------------+
| **OpenID Connect Issuer**                 | Blank                                               |
+-------------------------------------------+-----------------------------------------------------+
| **Logout with OIDC Provider**             | Unchecked                                           |
+-------------------------------------------+-----------------------------------------------------+
| **Enable OIDC SLO Frontchannel Endpoint** | Unchecked                                           |
+-------------------------------------------+-----------------------------------------------------+
```

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

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

### Github Login Test

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

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

2. Click **Continue with Github**.

3. The user is redirected to Github. Login if necessary. The first time the user utilizes the OpenID auth, they will be prompted to accept
the access requested. Select **Authorize**

```{figure} /images/oidc/github/authorization.png
:align: center
**Github Auth**
```

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