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 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.

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

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.

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.

5. The card now shows Waiting for Entra.

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 and go to Entra ID → Enterprise apps → All applications.
2. Select New application, then Create your own application.

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.

4. Open Provisioning in the new app.

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).

2. For the authentication method, choose OAuth2 client credentials grant.
3. Paste the values from Step 1:
4. • 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.

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

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.

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

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

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

• 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.

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

4. Select Assign.

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:
4. • New Entra experience: Overview → Start provisioning. This also resumes a paused connection.
   • Legacy experience: Provisioning, set Provisioning Status to On, and select Save.

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.

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

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.

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

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
• Customize attribute mappings
• On-demand provisioning
• Entra licensing

Updated on: 12/11/2026