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

# SCIM

> Provision users into essentry from Microsoft Entra ID (or any SCIM 2.0 identity provider).

## Overview

essentry exposes a SCIM 2.0 endpoint that lets your identity provider push users into your essentry account. Once provisioning is set up, creating, updating, or deactivating a user in your IdP automatically mirrors the change in essentry — no manual invitations needed.

This guide walks through setting up SCIM with **Microsoft Entra ID** (formerly Azure AD). The steps on the essentry side are the same for any SCIM-compatible IdP; only the second half of this page is specific to Entra ID.

## Prerequisites

* A **Super Admin** in your essentry account.
* A Microsoft Entra ID tenant with permission to create and configure **Enterprise applications**.
* A test user in Entra ID you can safely assign to the application for the first sync.

## Step 1 — Create the SCIM integration in essentry

1. In the essentry dashboard, open **Settings → Company**, then in the Company Settings sidebar choose **Integration Manager → Integrations**.
2. Under **Built-in Cloud Integrations**, click **SCIM**.
3. Enter an **Internal name** for the integration (e.g. `EntraID`) and click **Create**.

A new **SCIM** section appears in the integrations list with two values you will copy into Entra ID in the next step:

| Field          | Purpose                                                  |
| -------------- | -------------------------------------------------------- |
| `Endpoint URL` | The SCIM base URL your IdP will call.                    |
| `Token`        | Bearer token used to authenticate provisioning requests. |

Both values are hidden behind **Privacy Mode** by default. Click **Privacy Mode: ON** to reveal them so you can copy them.

<Warning>
  The SCIM token grants write access to your entire essentry user directory — treat it like a password. Anyone who obtains it can create, modify, or remove any user — **including Super Admins** — and disable their dashboard sign-in until the token is rotated.

  If it leaks, **disconnect the SCIM integration** in essentry and create a new one, then update the **Secret token** in your IdP's provisioning configuration.
</Warning>

## Step 2 — Create the Enterprise Application in Entra ID

1. Sign in to [entra.microsoft.com](https://entra.microsoft.com) as a tenant administrator.
2. In the left menu, open **Enterprise apps** → **New application**.
3. Click **Create your own application**, give it a name (e.g. `essentry SCIM`), and choose **Integrate any other application you don't find in the gallery (Non-gallery)**.
4. Click **Create**. Entra creates the application and opens its overview page.

## Step 3 — Connect provisioning to essentry

1. In the new application, open **Provisioning** from the left menu.
2. Click **Connect your application** (or **+ New configuration** if you are using the legacy experience and want to set provisioning mode to **Automatic**).
3. Fill in the connection form:
   * **Select authentication method**: `Bearer authentication`
   * **Tenant URL**: paste the `Endpoint URL` from Step 1.
   * **Secret token**: paste the `Token` from Step 1.
4. Click **Test connection**. Entra performs an authenticated request against the SCIM endpoint and reports success or failure.
5. Once the test succeeds, click **Create** at the bottom of the panel. Entra saves the provisioning configuration and returns to the application overview.

## Step 4 — Assign users (and groups)

By default a new Entra application has no users assigned — meaning the provisioning job has nothing to sync. Assign at least one test user before turning provisioning on.

1. Open **Users and groups** in the left menu of the application.
2. Click **+ Add user/group**.
3. In **Users and groups**, search for and select the user(s) you want to provision (start with a single test user).
4. Click **Select**, then **Assign**.

The assignment is confirmed with `Application assignment succeeded`.

## Step 5 — Start provisioning

1. Return to **Overview** in the application's Provisioning section.
2. Click **Start provisioning** and confirm with **Yes**.

Entra now begins its initial provisioning cycle. Cycles run roughly every 40 minutes; the first one may take a few minutes to start.

To verify against a single user immediately without waiting for the next cycle, use **Provision on demand**:

1. Click **Provision on demand** from the left menu (or from the Quick actions tile on the Overview page).
2. Search for the assigned user, select them, and click **Provision**.
3. Entra reports the result inline — each modified attribute is listed, along with success or failure for the SCIM call.

## Step 6 — Verify in essentry

After a successful provisioning run, the test user appears in essentry under:

* **Settings → Company → Users** — for users who can sign in to the essentry dashboard.

Updates to a user's name or `userName` (their login email) in Entra propagate on the next cycle.

<Warning>
  **Removing a user cancels their upcoming appointments and notifies the invited
  guests.** When your IdP unassigns or soft-deletes a user, essentry deletes the
  account and cancels every appointment they were hosting — guests receive a
  cancellation email. Reactivating in your IdP re-creates the user on the next
  cycle, but past appointments and history are not restored.
</Warning>

## Attribute mapping

Entra's default SCIM mapping covers the attributes essentry expects. The relevant fields are:

| SCIM attribute    | Source in Entra            | Used by essentry as                |
| ----------------- | -------------------------- | ---------------------------------- |
| `userName`        | `userPrincipalName`        | Login email and primary identifier |
| `active`          | Inverse of `IsSoftDeleted` | Account activation flag            |
| `name.givenName`  | `givenName`                | First name                         |
| `name.familyName` | `surname`                  | Last name                          |
| `externalId`      | `mailNickname`             | Stable external ID                 |

essentry uses **`userName`** as both the user's email address and their dashboard login. Per the SCIM 2.0 spec `userName` is mandatory and must be unique, which is why essentry relies on it as the identifier. The `emails` attribute is **ignored**, even if your IdP sends it.

This means `userName` must contain the user's real email address. Entra's default mapping uses `userPrincipalName`, which is usually the real email, so no changes are needed — this is how a new Entra application is configured out of the box.

<Note>
  If your `userPrincipalName` uses a non-routable domain (e.g.
  `@yourtenant.onmicrosoft.com`) rather than the user's actual email, edit the
  mapping under **Provisioning → Attribute mapping** so that `userName` is
  sourced from the attribute that holds the real email (typically `mail`).
</Note>

You can adjust any of these mappings in **Provisioning → Attribute mapping** if your IdP uses different source fields, but the defaults work for most setups.

## Troubleshooting

**User is assigned in Entra but does not appear in essentry.**
Wait for the next provisioning cycle (\~40 minutes) or trigger **Provision on demand** for that user. Check **Provisioning logs** in the Entra application for per-user status and error details.