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

# Microsoft Entra ID (Azure AD)

> Connect OpenCX to Microsoft Entra ID (formerly Azure AD) with a SAML 2.0 enterprise application. Covers metadata exchange, claims, group assignment, Conditional Access, and SCIM provisioning.

Connect OpenCX to **Microsoft Entra ID** (formerly Azure Active Directory) with a SAML 2.0 enterprise application. This is the recommended path for organizations running on Microsoft infrastructure: Microsoft 365, Entra ID, or a hybrid Active Directory tenant synced to Entra.

<Info>
  **On-prem Active Directory only?** If you don't sync to Entra ID and federate directly from on-prem **Active Directory Federation Services (AD FS)**, follow the [generic SAML 2.0 guide](/security/sso/generic-saml). AD FS is a standards-compliant SAML IdP and works the same way, just with a different admin console.
</Info>

## Before you start

<Steps>
  <Step title="Confirm your Entra role">
    You need **Cloud Application Administrator**, **Application Administrator**, or **Global Administrator** in Entra ID to create and configure enterprise applications.
  </Step>

  <Step title="Have your OpenCX SP details ready">
    From your OpenCX onboarding contact you'll receive three values for your connection. Keep them open in a tab:

    | OpenCX value                                                      | Entra field it maps to                       |
    | ----------------------------------------------------------------- | -------------------------------------------- |
    | **SP Entity ID**: `https://auth.open.cx/sso/saml/{connection-id}` | Identifier (Entity ID)                       |
    | **ACS URL**: `https://auth.open.cx/sso/saml/{connection-id}/acs`  | Reply URL (Assertion Consumer Service URL)   |
    | **Sign-on URL**: `https://platform.open.cx/login`                 | Sign on URL (optional, enables the app tile) |

    `{connection-id}` is unique to your organization. Never reuse another tenant's.
  </Step>
</Steps>

## 1. Create the enterprise application

<Steps>
  <Step title="Open the Entra admin center">
    Go to [entra.microsoft.com](https://entra.microsoft.com) → **Identity** → **Applications** → **Enterprise applications**.
  </Step>

  <Step title="Create a new application">
    Click **New application** → **Create your own application**. Name it `OpenCX`, choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.
  </Step>

  <Step title="Open single sign-on setup">
    In the new app, go to **Manage → Single sign-on** and select **SAML**.
  </Step>
</Steps>

## 2. Configure the SAML settings

<Steps>
  <Step title="Set the Basic SAML Configuration">
    Edit **Basic SAML Configuration** and enter your OpenCX values:

    * **Identifier (Entity ID)** → your OpenCX **SP Entity ID**
    * **Reply URL (Assertion Consumer Service URL)** → your OpenCX **ACS URL**
    * **Sign on URL** → `https://platform.open.cx/login`

    Save.
  </Step>

  <Step title="Confirm the claims">
    Open **Attributes & Claims**. Entra sends the user's object ID as the Name ID by default. Change the Name ID to email so identities match across logins:

    * **Name ID**: format **Email address**, source attribute `user.mail` (fall back to `user.userprincipalname` if mailboxes aren't populated).

    Confirm these claims are present (Entra emits them by default; add any that are missing):

    | Claim name                                                           | Source attribute |
    | -------------------------------------------------------------------- | ---------------- |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail`      |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | `user.givenname` |
    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | `user.surname`   |
  </Step>

  <Step title="Add the group claim (for role mapping)">
    If you'll map Entra groups to OpenCX roles, click **Add a group claim** → choose **Security groups** (or **Groups assigned to the application** to keep the token small) → set the source to **Group ID**.

    <Tip>
      Entra emits group **object IDs**, not names. Copy the object ID of each group from **Entra → Groups** and give them to OpenCX for the [role mapping](/security/sso/scim#role-mapping). Names change; object IDs don't.
    </Tip>
  </Step>
</Steps>

## 3. Hand your metadata to OpenCX

<Steps>
  <Step title="Download the Federation Metadata XML">
    In the **SAML Certificates** card, copy the **App Federation Metadata Url** (looks like `https://login.microsoftonline.com/{tenant-id}/federationmetadata/...`) **or** download the **Federation Metadata XML** file.
  </Step>

  <Step title="Send it to OpenCX">
    Provide the metadata URL (preferred; it auto-rotates the signing certificate) or the XML file to your OpenCX contact. We load it into your connection, which registers your IdP's entity ID, SSO endpoint, and signing certificate.
  </Step>
</Steps>

<Note>
  Prefer the **metadata URL** over the static XML. Entra rotates its SAML signing certificate periodically; the URL lets OpenCX pick up the new certificate automatically so logins don't break on rotation day.
</Note>

## 4. Assign users and groups

Entra only lets **assigned** identities sign in to the app.

<Steps>
  <Step title="Assign your pilot users">
    Go to **Manage → Users and groups → Add user/group** and assign a small pilot set (or a test group) first.
  </Step>

  <Step title="Expand to production groups">
    Once the pilot logs in cleanly, assign the security groups that should have OpenCX access. These are the same groups you map to roles.
  </Step>
</Steps>

## 5. Apply Conditional Access (recommended)

Because OpenCX is now an Entra enterprise app, your **Conditional Access** policies can target it directly.

<AccordionGroup>
  <Accordion title="Require MFA for OpenCX" icon="key">
    Create a policy scoped to the OpenCX app that requires multi-factor authentication. Every OpenCX login now inherits your MFA posture; OpenCX itself needs no separate MFA setting.
  </Accordion>

  <Accordion title="Restrict by device or network" icon="laptop-mobile">
    Scope access to compliant / Entra-joined devices, or to your corporate network ranges, so OpenCX is only reachable from managed contexts.
  </Accordion>

  <Accordion title="Block legacy auth" icon="ban">
    OpenCX uses modern federation only. Blocking legacy authentication for the app has no downside and closes a common attack path.
  </Accordion>
</AccordionGroup>

## 6. Test the login

<Steps>
  <Step title="Run Entra's built-in test">
    Back on the **Single sign-on** page, click **Test** and sign in as an assigned pilot user. Entra validates the round trip before you touch production.
  </Step>

  <Step title="Test SP-initiated login">
    In a private window, go to [platform.open.cx](https://platform.open.cx), enter your work email, and confirm you're redirected to Entra and land in the OpenCX Inbox.
  </Step>

  <Step title="Confirm the role">
    Check that the pilot user received the expected OpenCX role from your group mapping. If everyone lands as the default role, revisit the [group claim](#3-hand-your-metadata-to-opencx) and [role mapping](/security/sso/scim#role-mapping).
  </Step>
</Steps>

## 7. (Optional) SCIM provisioning

For automatic provisioning and, most importantly, automatic **deprovisioning** when someone is disabled in Entra, enable SCIM.

<Steps>
  <Step title="Request a SCIM token from OpenCX">
    Ask your OpenCX contact for your **SCIM base URL** (`https://auth.open.cx/scim/v2/{connection-id}`) and a **bearer token**.
  </Step>

  <Step title="Configure provisioning in Entra">
    In the OpenCX enterprise app, go to **Manage → Provisioning** → set mode to **Automatic**, paste the **Tenant URL** (SCIM base URL) and **Secret Token**, then **Test Connection** and **Save**.
  </Step>

  <Step title="Map attributes and turn it on">
    Keep the default attribute mappings (email, given name, surname, active). Set **Scope** to *Sync only assigned users and groups*, then toggle **Provisioning Status** to **On**.
  </Step>
</Steps>

See [Provisioning & role mapping](/security/sso/scim) for the full attribute reference.

## 8. Enforce

When the pilot is clean and every active member resolves through Entra, ask OpenCX to enforce SSO for your domain. Read the [pre-cutover checklist](/security/sso/troubleshooting#before-you-enforce) first, and keep your [break-glass account](/security/sso/overview#enforcement-break-glass) credentials safe.

## Troubleshooting

| Symptom                                             | Likely cause                                                                                            |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `AADSTS50105`, user not assigned                    | The user isn't assigned to the enterprise app. Add them under **Users and groups**.                     |
| User logs in but lands as default role              | Group claim missing, or the object ID isn't in your OpenCX role mapping.                                |
| Name ID is a GUID, identities duplicate on re-login | Name ID is still `user.objectid`. Set it to **Email address** / `user.mail`.                            |
| Login worked yesterday, breaks today                | Entra rotated its signing certificate and OpenCX has the static XML. Switch us to the **metadata URL**. |

More in [Troubleshooting SSO](/security/sso/troubleshooting).