> ## Documentation Index
> Fetch the complete documentation index at: https://differentai-cleanup-ai-gateway-models-replacement.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Entra SCIM provisioning

> 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 super-admin.
* A working, domain-verified, tested, and enabled 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.

Do not broaden SCIM assignment scope until you have tested both SAML sign-in and
SCIM. Make sure at least one OpenWork owner can sign in through SAML and that
the current SSO configuration has passed OpenWork's **Test SSO before enabling
it** flow 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.

### Existing OpenWork accounts

SCIM can link a matching existing account only when the user is already an
active member of the connector's OpenWork organization. The account keeps its
existing user ID; provisioning does not grant a new organization role.

An existing account with no active membership in that organization returns
`409 Conflict` instead of being linked by email alone. Membership in another
organization, a removed membership, or a pending invitation does not qualify.
An authorized administrator must establish active membership through the normal
onboarding process before retrying. Brand-new accounts follow the normal SCIM
provisioning flow.

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

### Optional: grant organization Admin through an Entra group

After verifying the synchronized membership, an OpenWork owner or super-admin
can approve the team to grant organization `Admin`. The Entra group name and
SAML group attributes do not grant elevated access by themselves. Follow
[Team Admin access](/cloud/members-and-rbac#team-admin-access) for the checkbox,
membership controls, and reapproval rules when team sync is disabled or re-enabled.

Test with a member who has no direct Admin role or other Admin team grant:
confirm `Admin via {team name}`, remove them from the Entra group, wait for
successful provisioning, and confirm that inherited access is gone. Review
**Provisioning logs** if the change is still pending.

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