openwork/packages/docs/cloud/scim-microsoft-entra.mdx

---
title: "Microsoft Entra SCIM provisioning"
description: "Provision OpenWork members and teams from Microsoft Entra ID"
---

Use Microsoft Entra ID provisioning to create, update, and deactivate OpenWork
members automatically. Entra security groups can also become OpenWork teams
whose membership is managed by Entra.

## Before you start

You need:

- An OpenWork organization with Enterprise SSO and SCIM.
- An OpenWork owner, or a member who can manage security configuration.
- A working OpenWork SAML connection. Complete and test
  [Microsoft Entra SAML SSO](/cloud/sso-microsoft-entra) first.
- A Microsoft Entra role that can manage enterprise applications and
  provisioning.
- An Entra plan that supports assigning groups to enterprise applications if
  you want to synchronize groups.

Keep SSO enforcement off until you have tested both SAML sign-in and SCIM. Make
sure at least one OpenWork owner can sign in through SAML before relying on
Entra as the identity source.

## 1. Get the OpenWork connection values

In OpenWork, select the organization you want to connect, then open
**Settings → SCIM**.

Confirm that the page shows **SAML/SSO active**, then:

1. Select **Create connector**. If a connector already exists, select
   **Rotate token** only when you intend to replace its current secret.
2. Copy the **SCIM base URL**.
3. Copy the **SCIM bearer token** immediately. OpenWork shows the full token
   only after creating or rotating it.
4. To synchronize Entra groups as OpenWork teams, select **Enable team sync**
   under **Create teams from SCIM groups**.

You will enter these values in Entra:

| Entra field | Where to get the value |
| --- | --- |
| Tenant URL | OpenWork **Settings → SCIM → SCIM base URL**. It normally ends in `/api/auth/scim/v2`. |
| Secret Token | The one-time **SCIM bearer token** shown after you create or rotate the connector. |

Treat the bearer token like a password. Do not put it in tickets, screenshots,
or shared setup notes. Rotating it immediately invalidates the previous token,
so update Entra at the same time.

## 2. Configure provisioning in Entra

In the [Microsoft Entra admin center](https://entra.microsoft.com):

1. Open **Entra ID → Enterprise apps**.
2. Select the same enterprise application used for OpenWork SAML SSO.
3. Open **Provisioning**.
4. Select **Get started**, then choose **Automatic** provisioning.
5. Open **Connectivity** or **Admin Credentials**, depending on the Entra
   interface shown for your tenant.
6. Paste the OpenWork **SCIM base URL** into **Tenant URL**.
7. Paste the OpenWork **SCIM bearer token** into **Secret Token**.
8. Select **Test Connection** and wait for a successful result.
9. Save the configuration.

If **Test Connection** fails, confirm that the URL has no extra path or trailing
text and that the token has not been rotated since it was copied.

## 3. Review mappings and scope

Open **Attribute mapping** in the provisioning configuration. Entra should show
mappings for both **Users** and **Groups**.

For a controlled rollout, set **Scope** to **Sync only assigned users and
groups**. This limits provisioning to identities assigned under the enterprise
application's **Users and groups** page.

Use a stable, unique email address for the SCIM user name. If your Entra user
principal names use an `onmicrosoft.com` domain but users sign in to OpenWork
with another email domain, verify which Entra attribute is mapped to
`userName`. Keep the SAML NameID and SCIM identity consistent so Entra does not
create a second OpenWork member for the same person.

## 4. Assign test users and groups

In the enterprise application, open **Users and groups** and select **Add
user/group**.

Start with:

- One or two test users who can sign in through the configured SAML app.
- One assigned security group containing those users.

Assignments control which objects are in scope when provisioning is set to
**Sync only assigned users and groups**. Creating a group elsewhere in Entra is
not enough; assign it to the OpenWork enterprise application as well.

## 5. Test with Provision on demand

Open **Provisioning → Provision on demand**.

Test a user first:

1. Search for and select an assigned test user.
2. Select **Provision**.
3. Confirm that import, scope evaluation, matching, and the final action all
   succeed.
4. In OpenWork, open **Members** and confirm that the member appears with the
   expected email.

Then test a group:

1. Make sure the test group already contains at least one assigned test user.
2. Search for and select the assigned group.
3. Under **Selected users**, explicitly select up to five members to include in
   the on-demand test.
4. Select **Provision**.
5. Open the result's **Group membership operations** tab and confirm each member
   shows **Add member — Success**.
6. In OpenWork, open **Members → Teams** and confirm that the group appears as a
   SCIM-managed team with the expected members.

<Note>
Entra's on-demand group workflow can return a generic internal server error for
an empty group, or when no members are selected. This can happen before Entra
sends a group-create request to OpenWork. Add members and select them explicitly
for the on-demand test. Entra's regular background provisioning cycle can still
synchronize empty assigned groups.
</Note>

## 6. Start scheduled provisioning

After the on-demand tests pass:

1. Return to **Provisioning → Overview**.
2. Set **Provisioning Status** to **On**, or select **Start provisioning** in
   the newer Entra interface.
3. Save the change.
4. Check **Provisioning logs** after the first cycle completes.
5. Refresh OpenWork **Members** and **Teams** to verify the final state.

Regular provisioning is incremental. A newly assigned object might not appear
until the next cycle; use the Entra provisioning logs to distinguish a pending
cycle from a failed operation.

## Verify lifecycle changes

Before expanding the assignment scope, verify the complete lifecycle:

1. Remove a test user from the Entra group and confirm that OpenWork removes the
   user from the SCIM-managed team.
2. Disable or unassign a test user and confirm the expected OpenWork
   deprovisioning behavior.
3. Add another assigned group and confirm that OpenWork creates a second
   SCIM-managed team.

Change SCIM-managed teams in Entra, not in OpenWork. OpenWork keeps manually
created teams separate from identity-provider-managed teams.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| **Test Connection** fails | Incorrect Tenant URL, expired or rotated token, or copied whitespace | Copy the base URL and a current token again from OpenWork, then retest |
| User or group is not found in **Provision on demand** | The object is outside the provisioning scope | Assign it under the enterprise application's **Users and groups** page |
| Entra will not allow a group assignment | The tenant plan does not support assigning groups to enterprise applications | Enable a suitable Entra plan or test with directly assigned users |
| On-demand group provisioning reports an internal server error without an OpenWork request | The group is empty or no members were selected for the on-demand run | Add members, select up to five under **Selected users**, and retry |
| A group provisions but no OpenWork team appears | OpenWork team synchronization is disabled | Open **Settings → SCIM** and enable **Create teams from SCIM groups** |
| Entra creates a duplicate OpenWork member | SAML and SCIM use different email identifiers | Align the SAML NameID and the SCIM `userName` mapping |
| Entra reports success but OpenWork still shows the old state | The UI or incremental cycle has not refreshed | Refresh OpenWork, check Entra **Provisioning logs**, and review the SCIM health status in OpenWork |

For member and team behavior after provisioning, see
[Members and RBAC](/cloud/members-and-rbac).