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

# Set up SSO with Microsoft Entra ID

> Connect Microsoft Entra ID as your organisation's identity provider so your team signs in to Adclear with their existing Microsoft accounts.

Single sign-on (SSO) lets your team sign in to Adclear through Microsoft Entra ID (formerly Azure Active Directory), using the accounts and access policies you already manage there. Adclear supports Entra ID through SAML.

<Note>
  SSO is an organisation-level setting that applies to everyone on your email domain. Setting it up is a joint effort between your IT team and Adclear support.
</Note>

## Before you start

Make sure you have:

* Administrative access to the [Microsoft Azure portal](https://azure.microsoft.com/en-us/get-started/azure-portal)
* Permission to create and configure enterprise applications
* Permission to assign users to an enterprise application
* The email domain, or domains, your team signs in with (for example `@company.com`)

You'll also need a set of connection values (an Identifier and a Reply URL) that are unique to your organisation. Contact Adclear support to generate them before you begin. You'll enter them in Entra ID during setup.

## Set up the app in Entra ID

<Warning>
  Adclear support provides the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** in the steps below. Ask our team for these values for your organisation before you start.
</Warning>

<Steps>
  <Step title="Create the enterprise application">
    In the Azure portal, go to **Enterprise applications** and select **New application**. On the **Browse Microsoft Entra Gallery** page, select **Create your own application**.

    Give the app a name your team will recognise, such as "Adclear", choose **Integrate any other application you don't find in the gallery (Non-gallery)**, then select **Create**.
  </Step>

  <Step title="Assign users or groups">
    Open **Assign users and groups**, then select **Add user/group**. Choose the people or groups who should be able to sign in to Adclear, then select **Assign**.

    <Note>
      For advanced group assignment, see [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal?pivots=portal).
    </Note>
  </Step>

  <Step title="Enter the SAML settings">
    Under **Manage**, select **Single sign-on**, then choose **SAML**. In the **Basic SAML Configuration** section, select **Edit** and enter the values Adclear support gave you:

    * **Identifier (Entity ID)**: the value provided by Adclear
    * **Reply URL (Assertion Consumer Service URL)**: the value provided by Adclear

    Select **Save** and close the panel.
  </Step>

  <Step title="Check the attributes and claims">
    In the **Attributes & Claims** section, select **Edit** and confirm the email claim is present. Entra ID usually configures these by default, but it's worth checking to avoid sign-in errors.

    | Claim                                                                | Value            |
    | -------------------------------------------------------------------- | ---------------- |
    | `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`   |

    <Note>
      The email claim is required. Name claims are optional. If your organisation uses custom attribute names, update the **Value** column with your own attribute paths.
    </Note>
  </Step>

  <Step title="Copy the federation metadata URL">
    In the **SAML Certificates** section, copy the **App Federation Metadata URL**. You'll send this to Adclear support in the next section.
  </Step>
</Steps>

## What Adclear needs from you

To finish the connection, send Adclear support:

1. The **App Federation Metadata URL** you copied from the SAML Certificates section
2. The **email domain, or domains**, this SSO applies to (for example `@company.com`). Tell us whether to include subdomains such as `@team.company.com`.

## What happens next

Once you've sent those details, Adclear support:

1. Configures the SSO connection on our side
2. Tests it to confirm sign-in works end to end
3. Confirms with you when it's live

Your team can then sign in to Adclear with their Microsoft credentials.

<Warning>
  If existing users have email addresses on the SSO domain, they'll need to sign in through Entra ID once SSO is enabled. If that applies to your team, we recommend switching it on during off-peak hours.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users can't sign in">
    Check that each person is assigned to the enterprise application in Entra ID.
  </Accordion>

  <Accordion title="Sign-in fails with an attribute error">
    Confirm the attribute mappings, especially the email address claim.
  </Accordion>

  <Accordion title="Sign-in fails with a configuration error">
    Confirm the Identifier and Reply URL from Adclear were entered exactly as provided.
  </Accordion>
</AccordionGroup>

For anything else, contact Adclear support with details of the error you're seeing.

## Related pages

<CardGroup cols={2}>
  <Card title="Set up SSO with Okta" icon="key" href="/sso/okta">
    Use Okta as your identity provider instead.
  </Card>

  <Card title="How roles work" icon="user-shield" href="/how-roles-work">
    Understand what each role can do once your team signs in.
  </Card>
</CardGroup>