> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/identity-and-access-management/single-sign-on/ms-entra-id-oidc.md).

# MS Entra ID (OIDC)

## Prerequisites

<details>

<summary>Permissions required for registering and configuring an app in Microsoft Entra ID.</summary>

The account must have permission to manage applications in Microsoft Entra ID. Ideally the account should be in the Global Admin role to grant admin consent.

</details>

## Implement single sign-on (SSO)

It is recommended to use two separate browser tabs for the Azure (A) and Keycloak (K) portals to make it easier to apply the settings.

1. (A) In the first tab sign in to the [Azure Portal](https://portal.azure.com/).
2. (A) Search for **Microsoft Entra ID**. Expand *Manage* in the left pane and click **App registrations**.
3. (A) Select **Endpoints**.
4. (A) Copy the value from the **OpenID Connect metadata document** field.
5. (K) Open a new tab in your browser and sign in to the target Spark tenant. Access the **Keycloak console** from the [Navigation menu](/navigation/navigation-menu.md#user-menu).
6. (K) Select **Identity Providers** from the left pane.
7. (K) Expand the **Add Provider** dropdown and choose **OpenID Connect v1.0**.
8. (K) Find the **Discovery Endpoint** field and paste the **OpenID Connect metadata document**.
9. (K) Click on the **Show metadata** link. You'll notice that some metadata fields are automatically filled in.
10. (K) Fill in values for the **Alias** and **Display Name** fields. The **Alia***s* should be a lowercase name without special symbols. Please note this **Display Name** will appear in the button on the Spark sign in page.
11. (K) Copy the **Redirect URI** value.
12. (A) Switch to Microsoft Entra ID. Select **App registrations**, then select **New registration**.
13. (A) Enter a name for the application, e.g. `Coherent Spark UAT`.
14. (A) Select the supported account type that is appropriate for your organization.
15. (A) Under **Redirect URI**, copy the edited **Redirect URI** value from before.
16. (A) Select **Register**.
17. (A) Copy the **Application (Client) ID** from the **Overview** page.
18. (K) Return to Keycloak. In the **Client ID** field, paste the value copied in the previous step.
19. (A) Switch to Microsoft Entra ID. Go to **Certificates & secrets**.
20. (A) Select **New Client Secret** and fill out the **Description and Expiration** fields.
21. (A) Select **Add** and copy the value.
22. (K) Return to Keycloak. In the **Client Secret** field, paste the value copied in the previous step.
23. (K) Scroll to the bottom of the page and click **Save**.
24. (A) Switch to Microsoft Entra ID. Go to **API permissions**.
25. (A) Select **Grant admin consent for {your Microsoft Entra ID}** to grant permissions to the application.
26. Navigate to your Spark tenant and sign in using the newly created provider. There will be a button on the Keycloak sign in page with the display name defined earlier.

## Configure certificate-based client authentication

It is recommended to replace the client secret configured in the previous section with certificate-based client authentication.

1. (K) In the **Keycloak Admin Console**, select **Realm settings** from the left pane, then select the **Keys** tab.
2. (K) Locate the active **RSA** key and select **Certificate**.
3. (K) Copy the certificate content displayed in the **Certificate** window and save it as a `.cer` file, for example `RSA.cer`.
4. (K) Select **Identity Providers** from the left pane, then select the identity provider configured in the previous section.
5. (K) In the **OpenID Connect settings** section, change **Client Authentication** to `JWT signed with private key`.
6. (K) Set **Add X.509 Headers to the JWT** to `On`.
7. (K) Scroll to the bottom of the page and select **Save**.
8. (A) Switch to Microsoft Entra ID. Select **App registrations**, then select the application created for the identity provider.
9. (A) Select **Certificates & secrets**, then select the **Certificates** tab.
10. (A) Select **Upload certificate** and upload the `.cer` file created in step 3.
11. (A) Select **Add** to complete the certificate upload.
12. Sign in to your Spark tenant using the identity provider to confirm that authentication is successful.

Certificate-based authentication avoids the use of a shared client secret. Keycloak instead signs a short-lived JWT client assertion with its private key, while Microsoft Entra ID uses the uploaded public certificate to verify the signature. The private key remains under Keycloak's control and is not shared with Microsoft Entra ID.

## Configure app roles to Spark user groups

{% hint style="info" %}
Do not configure a mapper for the `user:pf` group. This is the default minimal Spark group that users must belong to in order to sign in to Spark. Configuring a mapper for this group unnecessarily duplicates sign-in permission management already controlled by your Identity Provider.
{% endhint %}

It is recommended to use two separate browser tabs for the Azure (A) and Keycloak (K) portals to make it easier to apply the settings. In this guide, we will setup the automatic roles for the `tenant-admin` role.

1. (A) In the first tab sign in to the [Azure Portal](https://portal.azure.com/).
2. (A) Search for and select **Microsoft Entra ID.**
3. Select **App registrations**, then select the application you previously created and click *App roles*.
4. (A) Select ***Create app role.***
5. (A) Provide the following values then select **Apply**.

   | Key                                      | Value                     |
   | ---------------------------------------- | ------------------------- |
   | **Allowed member types**                 | `User/Groups`             |
   | **Display name**                         | `tenant-admin`            |
   | **Value**                                | `tenant-admin`            |
   | **Description**                          | Your app role description |
   | **Do you want to enable this app role?** | `True`                    |
6. (A) Click **Overview** in the left pane and then on your application in **Managed application in local directory**.
7. (A) Select **Properties** from the left pane.
8. (A) Set **Assignment required?** to `True` and select **Save**.
9. (A) Select **Users and Groups** from the left pane and then **Add user/group**.
10. (A) Assign your test account to the `tenant-admin` role.
11. (K) Open a new tab in your browser and sign in to the target Spark tenant. Access the **Keycloak console** from the [Navigation menu](/navigation/navigation-menu.md#user-menu).
12. (K) Select **Identity Providers** from the left pane and then the identity provider you configured in the previous section.
13. (K) Select the **Mappers** tab and then **Add mapper**.
14. (K) Provide the following values.

    | Name                   | Value                     |
    | ---------------------- | ------------------------- |
    | **Name**               | `tenant-admin`            |
    | **Sync mode override** | `force`                   |
    | **Mapper type**        | `Advanced Claim to Group` |
15. (K) Select **Add Claims**.
16. (K) Provide the following values:

    | Key     | Value          |
    | ------- | -------------- |
    | `roles` | `tenant-admin` |
17. (K) Leave **Regex Claim Values** as **Off** (which is the default).
18. (K) Select **Select Group***,* choose `tenant-admin` , then click **Select**.
19. (K) Select **Save**.
20. Sign in into Coherent Spark with your test account. Click on your initials and hover over the groups icon to confirm your membership in `tenant-admin`.
21. We highly recommend creating at least a few additional app groups relevant for [Private tenant](https://docs.coherent.global/tenant-administration/private-tenant)s:
    * Group for `supervisor:pf` user accounts. In Spark, `supervisor:pf` members can manage permissions across all folders.
    * Groups for "standard" user accounts, e.g. `user:teamA`, `user:teamB`. These groups can be assigned to the users in your organization not responsible for tenant administration. Creating multiple roles for "standard" user accounts can be useful to separate access between teams.

## Enable Privileged Identity Management (PIM)

See [MS Entra ID Privileged Identity Management (PIM)](/identity-and-access-management/single-sign-on/ms-entra-id-privileged-identity-management-pim.md).

## Create an enterprise application for Coherent Spark

See [Microsoft Apps](/identity-and-access-management/single-sign-on/microsoft-apps.md).