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

# Connect Microsoft Entra ID

> Import employees and groups from Microsoft Entra ID over SCIM and set up single sign-on, step by step, with an enterprise application you create in Entra.

Entra sends Cimento the people and groups you assign to a Cimento enterprise application and keeps them up to date over SCIM. The same application sets up SAML single sign-on, so assigned employees sign in to Cimento through Entra.

## Before you start

* An Entra Application Administrator, Cloud Application Administrator or Global Administrator, to create the application and set up provisioning and single sign-on.
* A Cimento user with the Admin role, to reveal the secret token in step 4. Integrations admins can do every other step.
* An email address on everyone you'll assign. Cimento matches people by email, so each person needs the **Email** field set on their Entra account.
* Microsoft Entra ID P1 or P2 if you want to assign groups. With Microsoft Entra ID Free, you assign people one at a time.
* Your organization's email domains registered with Cimento. Single sign-on only covers those domains, so ask your Cimento contact to add any that are missing.

<Note>
  Your organization connects one directory, and switching to another later needs Cimento support. As soon as you click **Begin Setup**, employees come from Entra: you can no longer add or upload employees in Cimento, or edit their names, email addresses, status or departments.
</Note>

## Steps

<Steps>
  <Step title="Start setup in Cimento">
    Go to **Admin → Integrations → Employee data**. Under **Directory provider**, choose Microsoft Entra ID and click **Begin Setup**. The setup guide opens at **Before you start**. Read it, then click **Next**.
  </Step>

  <Step title="Create the application">
    Click **Open the Microsoft Entra admin center**. Go to **Entra ID › Enterprise apps** (**Enterprise applications** in the Azure portal) and click **New application**, then **Create your own application**. Name it Cimento, choose **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**. The application's **Overview** page opens after a few seconds. Back in Cimento, click **Next**.
  </Step>

  <Step title="Assign people">
    In the Cimento application, open **Users and groups** and click **Add user/group**. Choose the people and groups who should use Cimento, then click **Select** and **Assign**. Assign yourself too: once single sign-on is on, you sign in to Cimento through Entra as well. Entra only sends direct members of a group you assign, not members of groups nested inside it. Back in Cimento, click **Next**.
  </Step>

  <Step title="Connect provisioning">
    In the Cimento application, open **Provisioning** and click **Connect your application**. If you see **Get started** instead, click it and set **Provisioning Mode** to **Automatic**. Keep **Bearer authentication**. From Cimento's **Provisioning** step, copy the **Tenant URL** into Entra, then click **Copy** next to **Secret Token** and paste it into Entra's **Secret token** field. Click **Test connection**, and when it succeeds, click **Create** or **Save**. You don't need to change the attribute mappings.
  </Step>

  <Step title="Start provisioning">
    On the provisioning **Overview**, click **Start provisioning**. In the older layout, set **Provisioning Status** to **On** and click **Save**. Keep the scope at **Sync only assigned users and groups**. Entra syncs about every 40 minutes. To check it right away, use **Provision on demand** with your own account. Back in Cimento, click **Next**.
  </Step>

  <Step title="Set up single sign-on">
    In the Cimento application, open **Single sign-on** and choose **SAML**. Click **Edit** in **Basic SAML Configuration**. Click **Add identifier** and paste the **Identifier (Entity ID)** from Cimento's **Single sign-on** step. Click **Add reply URL** and paste the **Reply URL (Assertion Consumer Service URL)**. Leave **Sign on URL**, **Relay State** and **Logout Url** empty, and click **Save**.
  </Step>

  <Step title="Send email addresses as the user identifier">
    In **Attributes & Claims**, click **Edit**, then the **Unique User Identifier (Name ID)** claim. Set **Name identifier format** to **Email address**, **Source** to **Attribute** and **Source attribute** to `user.mail`, and click **Save**. Back in Cimento, click **Next**.
  </Step>

  <Step title="Turn on single sign-on">
    <Warning>
      Saving the metadata URL moves sign-in to Entra at once for everyone with an address in your domains. Only people assigned to the Cimento application who are already in Cimento can sign in, so finish steps 3 to 5 first and make sure you're assigned.
    </Warning>

    On Entra's **Single sign-on** page, copy the **App Federation Metadata Url** from **SAML Certificates**. Paste it into Cimento's **Metadata URL** step and click **Save configuration**. When Cimento shows **SSO configured**, people who sign in to Cimento with an address in your domains are sent to Entra.
  </Step>

  <Step title="Verify">
    In Cimento's **Verify** step, click **Test connection**. It checks that single sign-on is connected to your Entra tenant and activates the integration. Then try it yourself: open [My Apps](https://myapps.microsoft.com) and select Cimento, or sign in to Cimento with your work email. Entra's **Test connection** in step 4 is the check for provisioning, and Entra's **Provisioning logs** show each person it sent.
  </Step>
</Steps>

## If something goes wrong

| Cimento shows | What to do |
| - | - |
| Single sign-on could not be set up from that URL | Check that you copied the **App Federation Metadata Url** from **SAML Certificates**, then save it again. |
| Your organization has no email domains set up yet | Ask your Cimento contact to add your email domains, then save the metadata URL again. |
| Single sign-on for your organization's domains is already connected with a different metadata URL | Contact Cimento support to change it. |
| Single sign-on is not connected for your organization yet | Go back to the **Metadata URL** step and save it again. |
| Single sign-on for your organization's domains is connected to a different identity provider or Microsoft Entra tenant | Contact Cimento support to switch it. |
| You don't have permission to view this value | Ask a Cimento user with the Admin role to copy the secret token for you. |

## What Entra sends

Cimento uses each employee's primary email, name, title, department, manager and phone numbers, and mirrors the groups you assign. See [What Okta and Microsoft Entra ID send](/getting-started/employee-directory#what-okta-and-microsoft-entra-id-send) for how each attribute maps and what happens when someone leaves.

## Stop provisioning

The secret token lets Entra create, update and deactivate employees in Cimento, so store it like a password. To stop Entra from updating Cimento, click **Stop provisioning** on the provisioning **Overview** (in the older layout, set **Provisioning Status** to **Off**), or delete the enterprise application.