> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.caimera.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set Up User Provisioning (SCIM) with Microsoft Entra

Connect Microsoft Entra to your Caimera workspace to provision people before their first sign-in, keep their contact email in sync, and remove access automatically when you disable them in Entra. You set this up once, with an OAuth Client ID and Client secret generated in Caimera.

SCIM is separate from Microsoft sign-in (SSO). SSO signs people in. SCIM creates and disables their directory identities.

What Entra can do in Caimera:

* **Provision** people before they first sign in. This creates a directory identity only: no Caimera account, no seat.
* **Keep identity stable** using the Entra tenant ID and each person's object ID. Changing a UPN or email never replaces an established identity.
* **Sync email** when a managed contact email changes on a verified, linked account.
* **Deactivate** a linked member: they are signed out, lose MCP access, and stop using a seat. Their work stays in the workspace.
* **Reactivate** them when you turn them back on, if membership and seat rules allow it.

SCIM does not sync groups, passwords or names. You can assign an Entra group to choose which users sync, but Caimera does not create group objects. A new account's display name comes from their Microsoft sign-in.

## Before you start

* **Caimera:** workspace administrator access, with your Microsoft organization connected, verified and tested in **Settings → SSO**. SCIM must use the same tenant. If SSO isn't set up, follow [Set up Microsoft SSO for your Caimera workspace](https://help.caimera.ai/en/article/set-up-microsoft-sso-for-your-caimera-workspace-npa9xd/) first.
* **Microsoft:** the **Application Administrator** or **Cloud Application Administrator** role. Global Administrator isn't required. Delegated owners of the app can also manage it.
* **Licence:** Microsoft lists automatic SaaS user provisioning under Entra ID Free. Group-based assignment and other premium features may need a paid licence.
* **A test user**, so you can check the setup before rolling it out.
* **A password manager** to hold the Client secret during setup. Never put it in screenshots or support messages.

People don't need to be Caimera members before you provision them. A directory identity doesn't grant workspace access or reserve a seat. When they sign in, Caimera checks account ownership, invitations or join policy, membership and seats.

## Step 1: Generate credentials in Caimera

1. Go to **Settings → SSO** and check that your Microsoft organization shows **Connected** and **Sign-in verified**.

![Microsoft organization connected and sign-in verified](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/01-sso-connected_esp90o.png =600x274)

2. On the **User provisioning (SCIM)** card, select **Generate OAuth credentials**.

![Generate OAuth credentials](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/02-generate-oauth-credentials_1xbyn3x.png =600x200)

3. Copy all four values: **Tenant URL**, **OAuth token endpoint**, **Client ID** and **Client secret**. The secret is masked: the eye button reveals it, and Copy works without revealing it.

![Copy the four SCIM credential values](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/03-copy-scim-credentials_m4iil0.png =450x409)

4. The Client secret is shown only in this dialog. Once it's saved safely, tick **I have copied the client secret** and select **Done**. A green tick next to a field means you copied it.

![Confirm the secret is saved, then select Done](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/04-confirm-secret-saved_1qe8y8g.png =450x429)

5. The card now shows **Waiting for Entra**.

![SCIM card waiting for Entra](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/05-waiting-for-entra_parmf4.png =600x333)

Always copy the URLs from your own workspace rather than typing them. In production they are usually `https://app.caimera.ai/api/scim/v2` and `https://app.caimera.ai/api/scim/oauth/token`.

The Client secret expires **three years** after you create it. Caimera emails active workspace admins within 30 days of expiry, but set your own reminder too.

## Step 2: Create the enterprise app in Entra

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) and go to **Entra ID → Enterprise apps → All applications**.
2. Select **New application**, then **Create your own application**.

![Enterprise apps: New application](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/06-new-application_zcrsw7.png =600x274)

![Create your own application](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/07-create-your-own-application_kcgksc.png =600x274)

3. Enter a name, for example **Caimera-SCIM**, choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.

![Name the app and choose Non-gallery](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/08-name-non-gallery-app_1w84chr.png =600x283)

4. Open **Provisioning** in the new app.

![Open Provisioning](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/09-open-provisioning_hb544l.png =600x273)

Use the Client ID and secret from Caimera, not credentials from a Microsoft app registration. Leave your existing SSO setup as it is: this connection doesn't replace it.

## Step 3: Connect Entra to Caimera

1. In **Provisioning**, select **New configuration** or **Connect your application** (the label depends on your Entra experience).

![Connect your application](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/10-connect-your-application_fwd3ud.png =600x276)

2. For the authentication method, choose **OAuth2 client credentials grant**.
3. Paste the values from Step 1:
    * **Tenant URL** ← Tenant URL
    * **OAuth token endpoint** ← OAuth token endpoint
    * **Client identifier** ← Client ID
    * **Client secret** ← Client secret
4. Leave **How credentials are sent** as **Header**, and leave **Scope** empty.

![OAuth2 client credentials grant fields](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/11-oauth-client-credentials_xlgm7s.png =600x302)

5. Select **Test connection**. When it succeeds, select **Create** or **Save**.

![Test connection](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/12-test-connection_19argfb.png =600x263)

Don't paste the Client secret into a long-lived **Secret Token** field. A successful test confirms the connection works, not that every user has synced.

## Step 4: Set up attribute mapping

1. Open **Attribute mapping** and select **Users**.

![Attribute mapping, Users tab (default rows)](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/13-attribute-mapping-users_rhb6zg.png =600x271)

2. Select the pencil next to a row to edit it, select **Apply**, then **Save** at the bottom of the page.

![Edit a mapping with the pencil](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/14-edit-mapping_dddhnn.png =600x276)

3. Set up exactly these four rows and remove the other profile, address and phone rows:

| Source attribute or expression | Mapping type | Target attribute | Apply this mapping | Match objects using this attribute |
| --- | --- | --- | --- | --- |
| objectId | Direct | externalId | Only during object creation | Yes, precedence 1 |
| userPrincipalName | Direct | userName | Always | No |
| mail | Direct | emails[type eq "work"].value | Always | No |
| `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | Expression | active | Always | No |

When you're done, the Users mappings should look like this:

![Final Users mappings](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/15-final-user-mappings_1r7rz2t.png =600x323)

* **externalId** must be the user's **objectId**, not the tenant ID or an application ID. It never changes.
* **active** must use **Mapping type → Expression**, with the formula pasted into the **Expression** field. If you paste it into Source attribute with Direct, Entra fails with `SchemaInvalid`. IsSoftDeleted covers disabling, unassigning and scoping changes.
* Keep UPN and contact email separate, including for guests. Don't use UPN as an email fallback.
* Don't map **displayName**, **name.givenName** or **name.familyName**. Caimera ignores them.
* Keep the **Create**, **Update** and **Delete** target object actions on. Create only makes a directory identity and uses no seat. Delete deactivates the identity in Caimera and keeps the member's work.
* Turn off group provisioning.

## Step 5: Scope and assign users

1. Set the provisioning scope to **Sync only assigned users and groups**.
2. Open **Users and groups** and select **Add user/group**.

![Users and groups](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/16-users-and-groups_1los17y.png =600x279)

![Add user/group](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/17-add-user-group_gjabr6.png =600x275)

3. Under **Users and groups**, select **None Selected**, tick the users (or groups, if your licence supports group assignment), and select **Select**.

![Add Assignment: None Selected](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/18-none-selected_1knk8tu.png =600x270)

![Tick users, then Select](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/19-select-users_95tghd.png =600x285)

4. Select **Assign**.

![Assign](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/20-assign_6t959q.png =600x284)

Start with one test user before assigning the wider organization. You can assign people who aren't Caimera members yet: Entra creates their directory identity without creating an account or using a seat.

## Step 6: Test and start provisioning

1. Open **Provision on demand**, pick your assigned test user, and select **Provision**. Check the result in **Provisioning logs**. Success means the directory identity exists, not that a member or seat was created.
2. Have the test user sign in with your workspace's Microsoft sign-in link. If Caimera finds an existing account with their email, they confirm they own it, either from a signed-in session or with a code sent to that account's email.
3. Start provisioning:
    * **New Entra experience:** **Overview → Start provisioning**. This also resumes a paused connection.
    * **Legacy experience:** **Provisioning**, set **Provisioning Status** to **On**, and select **Save**.

![New experience: Overview, Start provisioning](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/22-start-provisioning_1xnyhzw.png =600x251)

![Legacy experience: Provisioning Status On, then Save](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/21-legacy-provisioning-on_dvt3xf.png =600x280)

Use **Start provisioning**, not **Restart provisioning**, to resume. Restart resets sync state and re-evaluates everyone. After the first cycle, Entra syncs about every 40 minutes, so changes aren't instant.

In Caimera, linked members show an **Entra** label on **Settings → Team**. People who only have a directory identity don't appear as members yet.

![Team member with the Entra label](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/23-team-entra-label_nlydy1.png =600x231)

The SCIM card shows **Active** and the last sync time. Check individual results in Entra's Provisioning logs.

![SCIM card Active with last sync time](https://storage.crisp.chat/users/helpdesk/website/-/c/8/b/f/c8bf533b39f9b00/24-scim-active-last-sync_11ywwgx.png =600x353)

## Step 7: Test deactivation and reactivation

Use a test account that has confirmed ownership and is linked to a Caimera member.

1. Disable the test user in Entra, or remove their assignment from the app.
2. Wait for the next provisioning cycle and check **Provisioning logs**. Provision on demand can't find disabled or deleted users, so don't use it for this test.
3. In Caimera, check the member is inactive, signed out, has lost MCP access and no longer uses a seat. Their work should still be there.
4. Re-enable the user, restore their assignment if needed, and wait for the next cycle.
5. Check that access returns. A member shown as **Waiting for seat** needs an admin to choose **Give seat** once a seat is free. Members blocked for other reasons stay blocked.
6. Have the member sign in again. Old sessions and MCP tokens aren't restored.

A matching email alone can't deactivate an existing Caimera account. The account must be linked through ownership confirmation first.

## Email and UPN behavior

* An established link uses tenant ID plus object ID. Changing UPN or email doesn't replace it.
* A UPN change only updates the directory username.
* A valid email change updates the linked account's email and its email-based sign-in.
* An email already used by another account returns `409`. Accounts are never merged automatically.
* Removing the email, or sending an invalid one, on a linked account returns `400` and keeps the current email. Send a valid replacement instead.
* An update without an email leaves it unchanged.
* Entra usually doesn't send empty values, so clearing **mail** in Entra may not reach Caimera. Set a valid replacement instead.

If neither Microsoft sign-in nor SCIM provides an email, Caimera can't create the account and the person sees "Microsoft did not provide an email address". Make the user's email available to Caimera in Entra, then have them try again.

## Managing your credentials

Both actions are on the **User provisioning (SCIM)** card in **Settings → SSO**.

| When | In Caimera | Then in Entra |
| --- | --- | --- |
| The secret is about to expire, was lost, or may have leaked | **Create new credentials** | Paste the new **Client ID** and **Client secret** in **Provisioning → Connectivity**, **Test connection**, **Save** |
| You want to stop syncing | **Revoke** | Pause provisioning too if you're retiring the connection |

New credentials replace both the Client ID and secret, and the old ones stop working immediately. Syncing pauses until Entra has the new pair.

Revoking stops future syncing only. It doesn't deactivate members or reactivate anyone already deactivated.

## Troubleshooting

| What you see | What to check |
| --- | --- |
| `401` `invalid_client` | Both credential fields, expiry and revocation. If the secret is lost or exposed, create new credentials and update Entra. |
| `403` | The failing endpoint and message, both copied URLs, and that SSO is enabled. A 403 doesn't always mean a wrong URL. |
| `409` asking for tenant verification | Finish and test your Microsoft organization setup in **Settings → SSO** first. |
| `409` uniqueness or identity conflict | externalId is the user's objectId, and their email or username isn't used by another account. Don't merge accounts or change object IDs to clear it. |
| `400` email error | Send a valid contact email. If an email change and a disable were sent together and rejected, neither applied. Send the disable on its own. |
| `SchemaInvalid` on active | The active row uses **Expression**, with the formula in the Expression field. |
| Skipped or out of scope | Assignment, provisioning scope, scoping filters, target actions and matching attribute. Caimera membership isn't required. |
| `RedundantExport` | Nothing mapped has changed. Changing displayName won't help, as Caimera ignores it. |
| Enabled in Entra but no access in Caimera | Membership status, join policy, free seats, ownership confirmation and admin blocks. Enabled in Entra doesn't guarantee a seat. |
| Unexpected server error | Note the **X-Request-Id** or **Reference** value and the time, and send those to us. |

Before a wide rollout, set up Entra quarantine notification emails and review accidental-deletion protection.

Still stuck? Reach us via the chat bubble or at contact@caimera.ai with your workspace name, the reference value and roughly when it happened. Never send secrets, tokens, codes or screenshots showing them.

## Microsoft references

* [Configure a non-gallery SCIM connection](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups)
* [Customize attribute mappings](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes)
* [On-demand provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand)
* [Entra licensing](https://learn.microsoft.com/en-us/entra/fundamentals/licensing)