> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/configuration/sso-configuration/azure-ad-oidc.md).

# Azure AD (OIDC)

Configure SSO via Microsoft Entra (Azure AD) as an OpenID Connect identity provider for Silkline

## Overview

**Time to complete:** about 15 minutes

**What this does:** This configuration allows your users to login to Silkline using their Microsoft 365 / Azure AD account.

## Steps

These steps will guide you through setting up a new app registration in Microsoft Azure AD to enable Single Sign-On (SSO) into Silkline via OpenID Connect. Azure AD serves as the identity provider (IdP); Silkline's authentication service at `auth.silkline.ai` is the application Azure AD returns users to.

{% hint style="info" %}
Start with a setup link from **Settings → Single sign-on**. Open the link, choose **Microsoft Entra ID**, and use the callback shown on its setup page for the steps below. Your organization admin can share the link with your IdP administrator. See [Self-service SSO setup](https://docs.silkline.ai/configuration/sso-configuration/self-service-sso.md).
{% endhint %}

{% stepper %}
{% step %}

#### Register a New App in Azure AD

1. **Log in to Microsoft Entra (previously Azure Active Directory) Portal**:
   * Navigate to <https://entra.microsoft.com> and log in with your Azure AD admin credentials.
2. **Go to App Registrations**:
   * In the left-hand menu, select **Azure Active Directory** → **App registrations**
   * Select **New registration** button
3. **Register the Application**:
   * **Name**: Enter a name for the app, such as `Silkline-SSO`.
   * **Supported Account Types**: Please select Single Tenant
   * **Redirect URI**: Set this to your organization's Silkline redirect URI, with type `Web`:

     | Environment | Redirect URI                                                                |
     | ----------- | --------------------------------------------------------------------------- |
     | Production  | `https://auth.silkline.ai/realms/silkline/broker/<org-id>/endpoint`         |
     | Test / Gov  | `https://dev-auth-gov.silkline.ai/realms/silkline/broker/<org-id>/endpoint` |

     Generate a link in **Settings → Single sign-on** and copy the exact callback from its setup page. `<org-id>` is specific to your organization.
4. **Click "Register"** to create the app.

<figure><img src="https://1158234432-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwxUq49WUtHgRhcDnQkz%2Fuploads%2Fgit-blob-5775e9a619bbf2beb55f9aff7350ce4c8a0bb91b%2FScreenshot%202024-12-23%20at%2012.20.29%E2%80%AFPM.png?alt=media" alt=""><figcaption><p>Example screenshot of Microsoft Entra admin center configuration</p></figcaption></figure>
{% endstep %}

{% step %}

#### Gather App Details

1. From the **Overview** page of the app registration, and note down the following:
   * **Application (client) ID**: This is the Client ID for the Silkline connection.
   * **Directory (tenant) ID**: This identifies the Entra tenant containing the app.
2. On the setup form, use the tenant-specific issuer:

```
https://login.microsoftonline.com/<tenant-id>/v2.0
```

Confirm the tenant containing the app registration. Standard Microsoft 365 GCC uses `login.microsoftonline.com`; GCC High, DoD, and Azure Government use `login.microsoftonline.us`. An organization can have separate tenants in these clouds. Silkline's hosting environment does not determine the Entra issuer. See Microsoft's [national cloud deployments](https://learn.microsoft.com/en-us/graph/deployments).

Enter the issuer without the `/.well-known/openid-configuration` suffix.
{% endstep %}

{% step %}

#### Application Configuration

1. In **Authentication**, confirm the exact Silkline callback is registered under **Web**. Silkline uses a server-side authorization-code flow; enabling implicit ID-token issuance is not required for this connection.
2. Go to **Token configuration** and select **Add optional claim**.
3. Choose the **ID** token type and add:
   1. `email`
   2. `family_name`
   3. `given_name`
4. Review the OpenID `email` and `profile` permission requirements shown by Entra. Configure the required permissions under **API permissions** and follow your tenant's user/admin consent policy.
5. Check that the test user's Entra profile supplies an addressable email on one of your organization's verified Silkline domains. An email-shaped sign-in username and an optional claim do not populate an empty email attribute.
6. If application assignment is required, assign the intended users/groups in the app's **Enterprise applications → Users and groups** view.

See Microsoft's [authorization-code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) and [ID-token email claim reference](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference).
{% endstep %}

{% step %}

#### Connect the identity provider

Under **Certificates & secrets**, create a client secret and copy its **Value** — you will not be able to read it again. Do not copy the **Secret ID** shown next to it; Microsoft rejects it as the client secret.

Return to the setup page and enter the issuer, **Application (client) ID**, and client secret **Value**. Select **Connect identity provider**, then test sign-in.
{% endstep %}

{% step %}

#### Test SSO Configuration

1. Go to the [Silkline application](https://app.silkline.ai/landing).
2. Initiate the login flow to ensure the SSO integration with Azure AD works as expected.
3. Confirm that Silkline opens with the intended account and organization.
4. If issues occur, use [Troubleshooting](#troubleshooting) to match the message or Entra error code. Include the Entra sign-in event's request and correlation IDs when contacting support.
   {% endstep %}
   {% endstepper %}

### Video overview (third-party guide)

{% embed url="<https://www.youtube.com/watch?v=X3pI4B1-Lto>" %}

## Troubleshooting

For setup-link, browser-session, and shared account/domain errors, see [shared SSO troubleshooting](https://docs.silkline.ai/configuration/sso-configuration/troubleshooting.md).

### Setup form errors

| Message or symptom                                                      | Common cause                                                 | What to do                                                                                                                                                                |
| ----------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Expected https://login.microsoftonline.com/<tenant-id>/v2.0`           | The Entra issuer has the wrong host, tenant format, or path. | Use the tenant-specific v2 issuer. Do not paste the discovery-document URL, an app/client ID, or `/common` in the tenant field. Use `.us` for an Azure Government tenant. |
| `This is the Secret ID. Copy the secret's Value`                        | A GUID-shaped value was entered as an Entra secret.          | Copy the **Value** from **Certificates & secrets**. The **Secret ID** identifies the secret record and cannot authenticate the app.                                       |
| `Invalid client secret provided: this secret has expired`               | Entra reports an expired secret.                             | Create a new secret in the same app registration and enter its Value through a fresh setup link.                                                                          |
| `No application with this Client ID exists ... named by the Issuer URL` | The client ID is unknown in the selected Entra tenant/cloud. | Compare **Application (client) ID** and **Directory (tenant) ID** on the app's Overview page with the setup fields.                                                       |

Entra can mention Secret ID when a submitted secret Value is simply incorrect. Check the app/client ID pairing, full Value, and validity before choosing a fix.

### Entra error codes

These descriptions summarize Microsoft's codes. The Entra sign-in record is the best source for the specific tenant, application, policy, and request involved. See Microsoft's [error-code reference](https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes).

| Code                             | Meaning in this flow                                                        | Common solution                                                                                                                                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50011`                    | Entra rejects the requested reply/redirect URI.                             | Compare the actual request's `redirect_uri` with the setup page and the matching app registration's **Authentication → Web** entry. Check the entire scheme, host, organization path, and trailing slash.                             |
| `AADSTS900971`                   | The authorization request has no usable reply address.                      | Preserve the failed request and sign-in record. Confirm whether `redirect_uri` was sent, then compare it to the registered Web callback. The code alone does not establish a registration mismatch.                                   |
| `AADSTS700016`                   | The app identifier is not found in the requested directory.                 | Match client ID, tenant ID, issuer, and cloud to the same app registration.                                                                                                                                                           |
| `AADSTS7000215`                  | Client-secret authentication failed.                                        | Use the current secret **Value**, not Secret ID; check the app/client ID and whether the secret was copied completely or removed.                                                                                                     |
| `AADSTS7000218`                  | The token request omitted client-secret or client-assertion authentication. | Ask support to check the saved connection credentials and token-endpoint authentication method. Keep this connection configured as a confidential Web application; enabling public-client flows is not a remedy for this broker flow. |
| `AADSTS7000222`                  | The app's presented secret has expired.                                     | Create and securely configure a replacement secret, then complete a fresh user sign-in.                                                                                                                                               |
| `AADSTS65001`                    | The requested access lacks required user/admin consent.                     | Have the tenant's authorized admin review the requested permissions and consent policy. Request only the permissions needed for sign-in and claims.                                                                                   |
| `AADSTS65004`                    | Consent was declined.                                                       | Restart sign-in and review the consent request with the user or tenant admin.                                                                                                                                                         |
| `AADSTS50105`                    | The user does not have the required application assignment.                 | Check **Enterprise applications → the app → Users and groups** and the tenant's assignment policy. Assign the intended user/group if authorized.                                                                                      |
| `AADSTS50020`                    | The selected account cannot use the requested tenant/app context.           | Use the intended organization account. Ask the tenant admin to review guest membership and cross-tenant policy where applicable.                                                                                                      |
| `AADSTS50076` / `AADSTS50079`    | MFA or security-information registration is required.                       | Complete the required challenge or enrollment. Ask the tenant admin to investigate an enrollment loop.                                                                                                                                |
| `AADSTS53003`                    | Conditional Access blocked sign-in.                                         | Review the applied policy and its result in the Entra sign-in record. Meet its device, location, or authentication requirements.                                                                                                      |
| `AADSTS900439`                   | A US Government client was sent to the public-cloud endpoint.               | Confirm the tenant's cloud and use its correct authority. Azure Government uses `login.microsoftonline.us`; do not infer the cloud from Silkline's hosting environment.                                                               |
| `AADSTS50058` / `login_required` | There is no usable interactive Entra session.                               | Start an interactive sign-in. A silent probe returning this error does not verify callback registration, client-secret validity, or successful SSO.                                                                                   |

For `AADSTS7000218`, Microsoft's [confidential-client troubleshooting](https://learn.microsoft.com/en-us/troubleshoot/entra/entra-id/app-integration/confidential-client-application-authentication-error-aadsts7000218) explains the missing token-request credentials. The Silkline connection uses a confidential Web client.

Register the callback under **Web**, using the exact URL from the setup page. Silkline uses server-side authorization-code sign-in; implicit ID-token issuance is not required for this flow. See Microsoft's [authorization-code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) and [redirect URI guidance](https://learn.microsoft.com/en-us/entra/identity-platform/reply-url).

The Entra tenant containing the app registration determines the issuer. Standard Microsoft 365 GCC uses `login.microsoftonline.com`; GCC High, DoD, and Azure Government use `login.microsoftonline.us`. An organization can have separate tenants in these clouds. A government customer's organization name or a Silkline Gov environment does not identify the Entra cloud. See Microsoft's [national cloud endpoints](https://learn.microsoft.com/en-us/entra/identity-platform/authentication-national-cloud) and [national cloud deployments](https://learn.microsoft.com/en-us/graph/deployments).

### Email claims

For Entra, ask the identity admin to check the user's addressable email data and the app's ID-token claim configuration. Request `email` where required and confirm the test user's profile supplies a value. Adding an optional claim does not populate an empty source profile. Do not substitute `preferred_username` or a typed login hint for the returned email. Microsoft documents the [email claim's availability](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference).
