> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/dialogue-ai-assist/configure-microsoft-entra-id-for-deepdesk-sso.md).

# Configure Microsoft Entra ID for Deepdesk SSO

Configure a Microsoft Entra ID app registration for Deepdesk single sign-on.

Use Microsoft Entra ID to let users sign in to Deepdesk with single sign-on (SSO). This setup creates an app registration, configures the Deepdesk redirect URIs, adds the required token claims and permissions, and optionally creates app roles for Deepdesk access levels.

Deepdesk uses the Microsoft Entra ID configuration to authenticate users for Dialogue AI Assist. Your AnywhereNow representative or Deepdesk contact provides the tenant-specific Deepdesk URL and provider value that you need for the redirect URI.

## Before you begin

Verify that you have:

* access to the Microsoft Entra admin center;
* permissions to create and configure app registrations, API permissions, Enterprise Application assignments, and app roles;
* the Deepdesk redirect URI values for the tenant;
* the Deepdesk provider value to use in the SSO callback URI.

{% hint style="warning" %}
Redirect URIs must use HTTPS, are case-sensitive, and must match the values provided for the Deepdesk tenant exactly. Include the trailing slash when the supplied URI includes it.
{% endhint %}

## Create the app registration

1. In the Microsoft Entra admin center, go to **Identity** > **Applications** > **App registrations**.
2. Select **New registration**.
3. Enter a name, for example `Your Company Deepdesk SSO`.
4. For **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)**.
5. Select **Register**.
6. Copy the **Application (client) ID**. You need this value for the Application ID URI and for the values you provide to Deepdesk.

## Expose the Deepdesk API scope

1. Open the Deepdesk app registration.
2. Select **Expose an API**.
3. Next to **Application ID URI**, select **Add**.
4. Use this format, replacing the placeholder with the Application (client) ID:

   ```
   api://{your-application-client-id}
   ```
5. Select **Save**.
6. In **Scopes defined by this API**, select **Add a scope**.
7. Create a Deepdesk API scope with these values:

   | Setting                    | Value                                          |
   | -------------------------- | ---------------------------------------------- |
   | Scope name                 | `User.Read`                                    |
   | Who can consent            | **Admins and users**                           |
   | Admin consent display name | `Read user information`                        |
   | Admin consent description  | `Allows the app to read user information`      |
   | User consent display name  | `Read your user information`                   |
   | User consent description   | `Allows the app to read your user information` |
   | State                      | **Enabled**                                    |
8. Select **Add scope**.

{% hint style="info" %}
This Deepdesk API scope uses the name `User.Read`. You also add the Microsoft Graph delegated permission named `User.Read` later in this setup.
{% endhint %}

## Configure authentication and redirect URIs

1. In the app registration, select **Authentication**.
2. Under **Implicit grant and hybrid flows**, enable both options:
   * **Access tokens (used for implicit flows)**
   * **ID tokens (used for implicit and hybrid flows)**
3. Select **Save**.
4. Under **Platform configurations**, select **Add a platform**.
5. Select **Web**.
6. Add the Deepdesk redirect URIs:

   ```
   https://<tenant>.deepdesk.com/platform/sso/<provider>/callback/
   https://onboarding.deepdesk.com/oauth/callback/
   ```
7. Select **Configure** or **Save**.

## Add token claims

1. In the app registration, select **Token configuration**.
2. Select **Add optional claim**.
3. Select **ID** as the token type.
4. Add these optional claims:
   * `upn`
   * `preferred_username`
   * `login_hint`
5. Select **Add**.
6. Repeat the same steps for the **Access** token type.
7. If Microsoft Entra ID prompts you to add Microsoft Graph permissions for the claims, accept the prompt.

## Add API permissions and grant admin consent

1. In the app registration, select **API permissions**.
2. Select **Add a permission**.
3. Select **Microsoft Graph**.
4. Select **Delegated permissions**.
5. Add these Microsoft Graph delegated permissions:
   * `User.Read`
   * `openid`
   * `profile`
6. Select **Add permissions**.
7. Select **Grant admin consent for \[your organization]**.
8. Confirm the consent prompt.

## Optional: create a client secret

Create a client secret only when Deepdesk asks for one.

{% hint style="warning" %}
Copy the client secret value immediately after creation. The value is shown only once. Store and transfer it only through the approved secret-handling process.
{% endhint %}

1. In the app registration, select **Certificates & secrets**.
2. Select **New client secret**.
3. Enter a description and select an expiration period.
4. Select **Add**.
5. Copy the secret value immediately.

## Optional: create Deepdesk app roles

Create app roles when Deepdesk access should be assigned through Microsoft Entra ID. Add the roles on the application object so they can be assigned on the Enterprise Application.

1. In **App registrations**, open the Deepdesk app registration.
2. Select **App roles**.
3. Select **Create app role**.
4. Create the required roles. Use a human-readable display name and one of these role values:
   * `deepdesk.agent`
   * `deepdesk.editor`
   * `deepdesk.manager`
   * `deepdesk.assistant_editor`
5. For **Allowed member types**, select **Users/Groups**.
6. Add a description, enable the role, and save it.

## Assign app roles to users or groups

1. In the Microsoft Entra admin center, go to **Identity** > **Applications** > **Enterprise applications**.
2. Open the Deepdesk Enterprise Application.
3. Select **Users and groups**.
4. Select **Add user/group**, or edit an existing assignment.
5. Select the user or group.
6. Select the Deepdesk role to assign, for example `deepdesk.assistant_editor`.
7. Select **Assign**.

## Provide configuration values to Deepdesk

Provide these values to your Deepdesk contact:

| Value                     | Where to find it                     |
| ------------------------- | ------------------------------------ |
| Microsoft Entra tenant ID | Microsoft Entra ID overview page     |
| Application (client) ID   | App registration overview page       |
| Client secret             | Only if Deepdesk requires one        |
| Application ID URI        | `api://{your-application-client-id}` |

## Verify the configuration

Before users sign in with SSO, confirm that:

* the Application ID URI uses `api://{your-application-client-id}`;
* the Deepdesk API scope `User.Read` is created under **Expose an API**;
* both implicit grant and hybrid flow token options are enabled;
* the Deepdesk redirect URIs are configured under **Authentication** and match the supplied tenant and provider values;
* the optional claims `upn`, `preferred_username`, and `login_hint` are added for both ID and Access tokens;
* the Microsoft Graph delegated permissions `User.Read`, `openid`, and `profile` are added;
* admin consent is granted for the required permissions;
* Deepdesk app roles are created and assigned when role-based access is managed through Microsoft Entra ID.

## Troubleshooting

### Redirect URIs are not saved

* Confirm that every redirect URI starts with `https://`.
* Check the tenant name, provider value, capitalization, and trailing slash.
* Confirm that the redirect URI matches the value supplied by Deepdesk.

### Admin consent fails

* Confirm that you have permissions to grant admin consent for the organization.
* Confirm that all required Microsoft Graph delegated permissions are added before granting consent.

### SSO authentication fails

* Confirm that both access tokens and ID tokens are enabled under **Implicit grant and hybrid flows**.
* Confirm that the optional claims are configured for both ID and Access tokens.
* Confirm that the redirect URI in the sign-in request exactly matches one of the redirect URIs configured in Microsoft Entra ID.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/channels-integrations/dialogue-ai-assist/configure-microsoft-entra-id-for-deepdesk-sso.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.