# SCIM with Microsoft Entra ID

> Page: https://docs.plotwork.dev/scim-provisioning-entra-id. Index of every page: https://docs.plotwork.dev/llms.txt

Let Microsoft Entra ID (formerly Azure Active Directory) add, update and remove your organisation's members in Plotwork, and give them roles by group. You need Enterprise, and an email domain verified on the Single sign-on tab, as the [single sign-on guide](https://docs.plotwork.dev/single-sign-on.md#1-prove-your-email-domain) describes.

## TL;DR

| Entra ID field | Value from Plotwork |
|---|---|
| Where | Entra ID, Enterprise apps, your Plotwork app (or a new non-gallery app), Provisioning |
| Authentication Method | The bearer token one, not OAuth2 Client Credentials Grant or Workload Identity Federation |
| Tenant URL | The SCIM base URL: `https://api.plotwork.dev/scim/v2/<organisation id>` |
| Secret Token | The token from Make token, which starts with `pwscim_` |
| `userName` mapped from | `userPrincipalName`, or `mail` when people's principal name is not their address |
| `active` mapped from | `Switch([IsSoftDeleted], , "False", "True", "True", "False")`, the default |
| Matching attributes | `userName` for users, `displayName` for groups, the defaults |
| Test | Provision on demand, one person at a time |

## 1. Make the token in Plotwork

1. In the portal, open your organisation, then the Single sign-on tab.
2. Under Provisioning with SCIM, press Make token.
3. Copy the token now: it is shown once. Copy the SCIM base URL too.

## 2. Open provisioning in Entra ID

Provision from the enterprise application your people sign in with, so one app holds both. If you set up single sign-on with SAML, you already have it. If you signed in with an OpenID Connect app registration, or have no app yet, make one for provisioning:

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an Application Administrator.
2. Browse to Entra ID, then Enterprise apps.
3. Select New application, then Create your own application.
4. Name it `Plotwork`, choose Integrate any other application you don't find in the gallery (Non-gallery), and select Create.

Then, in the app, select Provisioning in the left panel, and New configuration. In the older screens, select Get started and set Provisioning Mode to Automatic.

## 3. Paste the values

| Entra ID field | Value |
|---|---|
| Authentication Method, under Admin Credentials, where Entra ID shows it | The long-lived bearer token. Plotwork does not offer OAuth2 Client Credentials Grant or Workload Identity Federation. |
| Tenant URL | The SCIM base URL from Plotwork, with nothing added at the end |
| Secret Token | The token from Plotwork |

Select Test Connection. Entra ID asks Plotwork for a user that does not exist and expects an empty list back; a pass means the address and the token work. Then select Create (or Save).

Leave the Secret Token filled in: an empty one makes Entra ID send its own token, which Plotwork refuses.

## 4. Check the attribute mappings

Select Attribute mapping (or Mappings) in the left panel. There are two sets.

Provision Microsoft Entra ID Users:

| Entra ID attribute | Plotwork attribute | What Plotwork does with it |
|---|---|---|
| `userPrincipalName` | `userName` | The person's address, which must be on a verified domain. Matching precedence 1. |
| `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` | Deactivates the person when they are unassigned, disabled or deleted |
| `givenName` | `name.givenName` | Kept |
| `surname` | `name.familyName` | Kept |
| `mailNickname` | `externalId` | Kept |
| `mail` | `emails[type eq "work"].value` | Read only when `userName` is not an address |

Other attributes in the default list, such as `jobTitle` or the phone numbers, are accepted and ignored. Leave them, or delete them to keep the mapping short.

If your people's user principal names are on a domain Plotwork has not verified, such as `acme.onmicrosoft.com`, edit the `userName` row and change its source attribute to `mail`. Keep `userName` as the only matching attribute: Plotwork does not filter on `emails`.

Provision Microsoft Entra ID Groups:

| Entra ID attribute | Plotwork attribute |
|---|---|
| `displayName` | `displayName`, matching precedence 1 |
| `objectId` | `externalId` |
| `members` | `members` |

Leave the group mapping on to push groups. Turn it off only if you will set every role by hand on the Members tab.

## 5. Choose who is provisioned

1. Under Settings, keep Scope at Sync only assigned users and groups.
2. Set a notification email and turn on accidental deletions prevention, as Microsoft recommends.
3. Open Users and groups in the app's left panel, select Add user/group, and assign the people and groups who should be members of the Plotwork organisation.

Assigning a group needs Microsoft Entra ID P1 or P2. On the free tier, assign people one by one. Nested groups are not followed: assign the group whose members you want.

## 6. Test with Provision on demand

1. Open Provisioning, then Provision on demand.
2. Search for one assigned person whose address is on your verified domain, and select Provision.
3. Entra ID shows its steps: Import user, Determine if user is in scope, Match user between source and target, and Perform action. A pass ends with the user created.
4. In Plotwork, the person is on the Members tab, and Provisioning with SCIM counts them.

You can also provision one group on demand with up to five of its members, which pushes the group so you can give it a role. Wait a few minutes after a new assignment: Entra ID takes a moment before Provision on demand sees it.

## 7. Start provisioning

Select Start provisioning, or set Provisioning Status to On and save. The first cycle can take a while. After it, Entra ID runs a cycle about every 40 minutes. Provisioning logs, in the app's left panel, list every call and its result.

## 8. Map groups to roles in Plotwork

Once Entra ID pushes the groups, they appear in Plotwork under Groups and roles in the same section. Choose Admin, Member, Reader or No role for each.

| While | A provisioned person's role |
|---|---|
| No group gives a role | Never changed by SCIM |
| Any group gives a role | The highest role their groups give, or Member when none of theirs gives one |

For example, assign `Plotwork admins` and `Plotwork readers` to the app, give the first Admin and the second Reader, and everyone else assigned on their own is a Member. The owner is never changed.

## What Entra ID does, and what Plotwork does

| In Entra ID | In Plotwork |
|---|---|
| A person is assigned, directly or through a group | They join the organisation as a member, within your member limit |
| Their name changes | The name follows within a cycle |
| They are unassigned, disabled or deleted | They leave the organisation at once, and every session they opened through your provider ends. Their API keys and agents stop at their next call. Their Plotwork account stays. |
| They are assigned again | They come back as a member, if there is room |
| A pushed group's members change | Their roles follow, once any group gives a role |

## Troubleshooting

Open Provisioning logs in the app and select a failed row: its Troubleshooting & Recommendations tab shows the status and the sentence Plotwork answered.

| What you see | What to check |
|---|---|
| Test Connection fails with 401 | The Secret Token is empty, or was replaced or revoked in Plotwork. Make a new token and paste it again. |
| Test Connection fails with 404 | The Tenant URL is not the one from Plotwork. Copy it again, with nothing added at the end. |
| Test Connection fails with 403 | The organisation is not on Enterprise. |
| "The address is not on a domain the organisation verified for single sign-on." | The person's user principal name is on another domain. Map `mail` to `userName`, as in step 4, or verify the domain in Plotwork. |
| "userName cannot change." | The person's principal name or mail changed in Entra ID. Unassign them, let a cycle run, and assign them again. |
| "A user with this userName already exists." | Entra ID lost track of a person it made, usually after the matching attribute changed. Keep `userName` as the matching attribute. |
| "The organisation has no free seats." | The member limit is reached. Raise it on the Members tab, or unassign someone. |
| "Filtering on ... is not supported." | A matching attribute other than `userName` is set. Set it back. |
| The app is in quarantine | Entra ID stopped after many failures. Fix the cause in the logs, then select Restart provisioning. |
| Nobody is provisioned | Nobody is assigned, or Scope is Sync only assigned users and groups with no assignments. Assign people or groups under Users and groups. |

## See also

| Page | Why |
|---|---|
| [Provisioning with SCIM](https://docs.plotwork.dev/scim-provisioning.md) | What Plotwork keeps, what it supports, and every refusal |
| [Single sign-on with Microsoft Entra ID](https://docs.plotwork.dev/single-sign-on-entra-id.md) | Signing the same people in through Entra ID |
| [SCIM with Okta](https://docs.plotwork.dev/scim-provisioning-okta.md) | The same for Okta |
| [Microsoft: provision users to a SCIM app](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#integrate-your-scim-endpoint-with-the-microsoft-entra-provisioning-service) | Microsoft's own steps for a non-gallery app |
| [Microsoft: provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand) | What each step of a test shows |