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

## Microsoft (Internal) OpenID Setup

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

Reference Docs:

- <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>
- <https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols>
- <https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims>

### Creating a Microsoft OAuth App

01. Login to the Microsoft Azure Portal: <https://portal.azure.com/>

02. Select **Azure Active Directory**.

    > ```{figure} /images/oidc/microsoft/azure_ad.png
    > :align: center
    > :width: 90%
    >
    > **Azure Active Directory**
    > ```

03. Select **App Registrations**.

    > ```{figure} /images/oidc/microsoft/app_registrations.png
    > :align: center
    > :width: 20%
    >
    > **App Registration**
    > ```

04. Select New Registration.

05. Give the app a Name (e.g {code}`Kasm`)

06. In the **Supported account types** select **Accounts in this organizational directory only...**.

    > ```{figure} /images/oidc/microsoft_internal/register_app.png
    > :align: center
    > :width: 70%
    >
    > **Register App**
    > ```

07. On the next page, the **Application (client) ID** is shown, save this value as the Client ID to be used in the next section.

08. Select **Endpoints**. Note the **OAuth 2.0 authorization endpoint (v2)** and **OAuth 2.0 token endpoint (v2)** values to be used in the next section.

09. Select **Add a certificate or secret** next to **Client credentials**.

    > ```{figure} /images/oidc/microsoft/client_credentials.png
    > :align: center
    > :width: 70%
    >
    > **Client Credentials**
    > ```

10. Select the **Client secrets** tab, then slick **New client secret**.

11. Enter a description and expiration then click **Add**.

12. The credentials are shown, save the **Value** as the **Client Secret** to be used in the next section.

    > ```{figure} /images/oidc/microsoft/client_secret.png
    > :align: center
    > :width: 70%
    >
    > **Client Secret**
    > ```

13. Select **Token configuration**.

14. Select **Add group claims**.

15. Check **Security groups**, then click **Save**.

    > ```{figure} /images/oidc/microsoft_internal/group_claims.png
    > :align: center
    > :width: 90%
    >
    > **Group Claims**
    > ```

### 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 Microsoft                                                        |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Logo URL**           | :code:`https://www.microsoft.com/favicon.ico`                                  |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Enabled**            | Checked                                                                        |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Auto Login**         | Unchecked                                                                      |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Hostname**           | <Empty>                                                                        |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Default**            | Checked                                                                        |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Client ID**          | <Client ID From Microsoft OAuth App>                                           |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Client Secret**      | <Client Secret from Microsoft OAuth App>                                       |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Authorization URL**  | <OAuth 2.0 authorization endpoint (v2) value from Microsoft OAuth App>         |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Token URL**          | <OAuth 2.0 token endpoint (v2) value fom Microsoft OAuth App>                  |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **User Info URL**      | :code:`https://graph.microsoft.com/oidc/userinfo`                              |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Scope**              | :code:`openid`                                                                 |
   > |                        | :code:`email`                                                                  |
   > |                        | :code:`profile`                                                                |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Username Attribute** | :code:`email`                                                                  |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Groups Attribute**   | :code:`groups`                                                                 |
   > +------------------------+--------------------------------------------------------------------------------+
   > | **Debug**              | Unchecked                                                                      |
   > +------------------------+--------------------------------------------------------------------------------+
   > ```
   >
   > ```{figure} /images/oidc/microsoft_internal/kasm_oidc_configuration.png
   > :align: center
   > :width: 70%
   >
   > **Kasm OIDC Configurations**
   > ```

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

### Microsoft Login Test

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

   > ```{figure} /images/oidc/microsoft/login.png
   > :align: center
   > :width: 50%
   >
   > **Login Screen**
   > ```

2. Click **Continue with Microsoft**

3. The user is redirected to Microsoft for auth.

   > ```{figure} /images/oidc/microsoft/authorization.png
   > :align: center
   > :width: 50%
   >
   > **Microsoft 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/microsoft_internal/groups.png
> :align: center
> :width: 90%
>
> **Add Group**
> ```

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 Microsoft" for the **SSO Provider**.
4. Then enter the Azure AD security group ID desired in the **Group Attributes** field.

> ```{figure} /images/oidc/microsoft_internal/sso_group_mapping.png
> :align: center
> :width: 90%
>
> **Add SSO Group Mapping**
> ```

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