> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kvelden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO with Microsoft Entra ID

> Connect Microsoft Entra ID (Azure AD) to Enclave for enterprise single sign-on via OIDC or SAML 2.0, with the exact field mappings and Entra-specific notes.

Connect Microsoft **Entra ID** (formerly Azure AD) to Enclave. Both **OIDC** and **SAML 2.0** are supported — pick one. See [Authentication](/organization/authentication) for how SSO fits with the rest of Enclave.

<Info>
  **Where:** **Organization → Single Sign-On** in Enclave (Owner role). One email domain maps to one connection.
</Info>

## Option A — OIDC (recommended)

<Steps>
  <Step title="Register an app in Entra">
    Entra admin center → **App registrations → New registration**.

    * **Redirect URI** (type **Web**): `https://<your-enclave-host>/api/auth/oidc/callback`
    * Copy the **Application (client) ID** and **Directory (tenant) ID**.
    * **Certificates & secrets → New client secret** → copy the secret **Value**.
    * **Token configuration → Add optional claim → ID → `email`** (Entra often omits `email` unless added; Enclave falls back to `upn`/`preferred_username`, but adding it is cleanest).
  </Step>

  <Step title="Add the connection in Enclave">
    **Add Connection → OIDC**:

    | Field                     | Value                                                |
    | ------------------------- | ---------------------------------------------------- |
    | Domain                    | your email domain                                    |
    | Issuer URL                | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
    | Client ID / Client Secret | from the previous step                               |
  </Step>

  <Step title="Verify domain, enable, test">
    Complete [domain verification](/organization/sso/okta#verify-your-domain), enable, and sign in.
  </Step>
</Steps>

<Note>
  If the ID token omits `email`, Enclave uses `preferred_username` / `upn` automatically.
</Note>

## Option B — SAML 2.0

<Steps>
  <Step title="Create an Enterprise application">
    Entra → **Enterprise applications → New application → Create your own application** → *Integrate any other application (Non-gallery)*. Then **Single sign-on → SAML**.
  </Step>

  <Step title="Basic SAML Configuration">
    | Entra field            | Value                                                                                                       |
    | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
    | Identifier (Entity ID) | your connection's **per-connection metadata URL** (`https://<host>/api/auth/saml/metadata/<connection-id>`) |
    | Reply URL (ACS)        | `https://<your-enclave-host>/api/auth/saml/acs`                                                             |

    Set **SAML Signing Certificate** to sign the assertion (Entra does by default), and download the **Certificate (Base64)**.
  </Step>

  <Step title="Add the connection in Enclave — map the fields">
    **Add Connection → SAML.** From Entra's **Set up single sign-on** panel:

    | Entra value                                                          | Enclave field                                        |
    | -------------------------------------------------------------------- | ---------------------------------------------------- |
    | **Login URL**                                                        | **SSO URL**                                          |
    | **Microsoft Entra Identifier** (`https://sts.windows.net/<tenant>/`) | **IdP Entity ID / Issuer**                           |
    | **Certificate (Base64)**                                             | **X.509 Certificate**                                |
    | *App Federation Metadata Url*                                        | **not used** (it's the config location, not a field) |

    <Warning>
      **IdP Entity ID / Issuer** = the **Microsoft Entra Identifier**
      (`https://sts.windows.net/<tenant-id>/`), not the federation metadata URL.
      A wrong value fails with `idp_issuer_mismatch`.
    </Warning>
  </Step>

  <Step title="NameID format">
    Entra often rejects the `emailAddress` NameID policy. If sign-in errors on NameID, set the connection's **NameID Format** to **Persistent** or **Unspecified**.
  </Step>

  <Step title="SP certificate, domain verify, enable">
    Generate the **SP signing certificate** on the connection card (one click), set Entra's **Identifier** to the per-connection metadata URL shown there, complete [domain verification](/organization/sso/okta#verify-your-domain), enable, and test.
  </Step>
</Steps>

<Note>
  **Signing-key rotation:** Entra rotates its signing certificate periodically. Enclave's certificate field accepts **multiple concatenated PEM certs** — paste the new one alongside the current before Entra switches over, so sign-in never breaks.
</Note>

## Shared steps & troubleshooting

Domain verification, SP-certificate generation, provisioning mode, Require-fresh-sign-in, and Single Logout work the same as for Okta — see the [Okta guide](/organization/sso/okta) and [Authentication](/organization/authentication). The [troubleshooting table](/organization/sso/okta#troubleshooting) (audience / issuer / signature / timing reasons) applies to Entra too.