Microsoft Entra ID User Provisioning (SCIM)
Outline
Overview
Connect Microsoft Entra ID to SAFE so that the users and groups you assign in Entra are created, updated and suspended in SAFE automatically, with SAFE roles set from their Entra groups.
What you get
- Automatic onboarding. Users assigned to the SAFE app in Entra are created in SAFE.
- Role from group. Each user gets the SAFE role mapped to their Entra group. A user in several mapped groups gets the role with the lowest order number. A user in no mapped group gets the default role.
- Automatic offboarding. A user removed from the app or disabled in Entra is suspended in SAFE. A user deleted in Entra is deleted in SAFE.
- Review before anything changes. When you turn provisioning on, SAFE lists who will be added, updated and removed, and applies the changes only after you confirm.
- No passwords shared with SAFE. Entra signs in to SAFE with a client ID and secret that SAFE issues for your tenant.
How it works
- Entra exchanges the client ID and secret for an access token at the OAuth Token Endpoint.
- SAFE issues a short-lived access token.
- Entra sends users and groups to the Tenant URL with the token.
SAFE never calls Entra. Entra exchanges the client ID and secret for an access token, then sends users and groups to SAFE's SCIM endpoint (the Tenant URL) with it. While the integration is disabled in SAFE, SAFE records what Entra sends and applies it when you enable the integration.
Before you start
You need an administrator on each side.
| Where | Who | What they need |
|---|---|---|
| SAFE | A SAFE administrator | Access to Integrations; provisioning enabled for your SAFE tenant |
| Microsoft Entra | At least an Application Administrator | Permission to create enterprise applications and configure provisioning |
Decide these before you begin:
- Mode. Hybrid allows SCIM-managed users and approved local accounts: Entra manages users on your allowed domains, and you can still add other users in SAFE. SCIM-only means all normal workforce accounts must come from Entra ID.
- Default role (required). The SAFE role for a user in no mapped group: a new user until Entra sends their groups, and a user who leaves every mapped group. Choose a low role. SAFE warns you if the default is an Admin role.
- Allowed domains (Hybrid mode, required). Only users with emails on these domains are synced from Entra. Existing SAFE users on these domains come under Entra's control, and their role is then set from your mappings.
- Which Entra group grants each SAFE role, and the order to use when a user is in several mapped groups.
- Your SAFE admins. SAFE refuses to turn provisioning on unless an Entra group is mapped to the Admin role, at least one active Admin remains, and you remain an Admin yourself. Put your SAFE admins in the Entra group you map to Admin.
- Who is in scope. Microsoft recommends syncing only the users and groups you assign to the app.
Step 1: Choose the mode and default role (in SAFE)
- In SAFE, open Integrations and select Microsoft Entra ID User Provisioning (SCIM).
- Under Connector Details, choose Hybrid mode or SCIM-only mode.
- Choose the Default role.
- In Hybrid mode, add your Allowed Domains: type a domain, for example
example.com, and press Enter. - Select Save. You can add role mappings later, after Entra's first sync.
Step 2: Generate credentials (in SAFE)
SAFE issues the credentials because Entra signs in to SAFE, not the other way round.
- Select Generate Credentials, then Generate to confirm.
- The Credentials card shows four values, named as Entra names them: Tenant URL, OAuth Token Endpoint, Client Identifier and Client Secret. Use the copy button next to each one. You paste them into Entra in Step 4.
Note
Copy the client secret now. SAFE shows it only once. If you lose it, generate credentials again: the client ID stays the same, SAFE adds a second secret, and the current one keeps working until you remove it.
Generating credentials does not turn provisioning on. That is a separate step after you have reviewed the changes (Step 8).
Step 3: Create the enterprise application (in Entra)
SAFE is not in the Entra app gallery, so you add it as your own application.
- Sign in to the Microsoft Entra admin center as at least an Application Administrator.
- Go to Entra ID > Enterprise apps.
- Select + New application > + Create your own application.
- Name it, for example
SAFE, and choose Integrate any other application you don't find in the gallery. - Select Add. Entra creates the app and opens its management screen.
Step 4: Connect provisioning and test the connection (in Entra)
Entra uses the OAuth 2.0 client credentials grant: it trades the client ID and secret for a short-lived access token, then calls SAFE's Tenant URL with it.
- In the app you created, select Provisioning in the left panel, then + New configuration. If the app already has a configuration, open Connectivity.
- For Authentication method, choose OAuth2 Client Credentials Grant.
- Paste the values from the SAFE Credentials card into the Entra fields with the same names, as the table below shows.
- Set two options. For How credentials are sent, any option works: SAFE accepts the client ID and secret in the header, the body, or both, as long as they match. For OAuth 2.0 scopes, leave the field empty: SAFE sets the token's scope itself.
- Select Test Connection. Entra looks up a user that does not exist, and SAFE answers with an empty list. A green message means the URL and credentials work.
- Select Create to save the provisioning job.
| SAFE Credentials card | Entra field |
|---|---|
| Tenant URL | Tenant URL |
| OAuth Token Endpoint | OAuth Token Endpoint |
| Client Identifier | Client Identifier |
| Client Secret | Client Secret |
Paste the Tenant URL exactly as SAFE shows it. It ends in /scim/v2/azure; do not add /scim or anything else to it.
In SAFE, the Credentials card now shows Last token request and, once Entra starts sending users, Last SCIM call. The badge shows Active while Entra has called SAFE within the last two hours and its latest call did not fail.
Note
Creating the job with Microsoft Graph? If you script the setup instead of using the portal, create the provisioning job from the
scimtemplate, notcustomappsso. In the portal, Attribute mapping labels the target attributes "customappsso"; that is expected.
Step 5: Choose who syncs (in Entra)
Entra provisions only the users and groups assigned to the app when the scope is Sync only assigned users and groups.
- Select Users and groups, then assign the users and the groups you want in SAFE. Assign every group you plan to map to a SAFE role, so Entra sends it to SAFE. Nested groups are not expanded: only direct members of an assigned group are provisioned.
- Select Attribute mapping and review the user and group mappings. SAFE reads the attributes in the table below.
- Under Overview > Properties, turn on notification emails for quarantine alerts and accidental-deletion prevention.
| Object | Attributes SAFE uses |
|---|---|
| User | userName (must equal the user's SAFE sign-in email; Entra fills it from the user principal name by default), emails, name.givenName, name.familyName, displayName, active, externalId |
| Group | displayName, externalId, members |
Review the attribute mapping before you start provisioning. Changing a user's email in Entra after they are provisioned is not supported.
Step 6: Start provisioning (in Entra)
- On the app's Provisioning page, select Start provisioning.
- Optional: use Provision on demand on one in-scope user first.
Provisioning is still turned off in SAFE at this point, so SAFE records what Entra sends without changing any SAFE user. The Credentials card shows how many changes from Entra are waiting. The first cycle takes longer than later ones. After it, Entra syncs about every 40 minutes, as Microsoft documents.
Step 7: Map Entra groups to SAFE roles (in SAFE)
Entra's groups appear in SAFE after its first sync. Until then everyone gets the default role.
- Open the Role Mapping tab and select Add Mapping.
- Choose the Entra group and the SAFE role it grants. Each group can be mapped once.
- Set the Order: type a number or drag the row. When a user is in several mapped groups, the lowest number wins.
- The Default row always comes last and covers all other groups and users. Change it with the Default role under Connector Details.
- Select Save.
Step 8: Review and turn provisioning on (in SAFE)
- Turn on the switch at the top right of the page. SAFE opens Review before enabling.
- Check each group in the review:
- Users Added: new SAFE users, with their role.
- Users Updated: role changes, shown as old role → new role.
- Users Removed: users that will be suspended or deleted, with the reason.
- Users Not Impacted: users that stay as they are, for example users outside your allowed domains or users whose role is not managed by Entra.
- Select Apply & Enable. SAFE applies the changes in the background and shows the progress under Connector Details, for example Applying changes · 120 of 400. When it finishes, it shows Synced. You can leave the page while it runs.
Note
If the review warns that Entra hasn't synced yet, cancel and run Entra provisioning first (Step 6). Otherwise, every SAFE user that Entra has not confirmed would be removed: all users in SCIM-only mode, or the users on your allowed domains in Hybrid mode.
SAFE disables Apply & Enable if the change would leave no active Admin, if no Entra group is mapped to Admin, or if you would lose Admin access yourself. Fix the mapping and try again.
From now on, Entra's changes apply as they arrive. When you change the mode, default role, domains or mappings while provisioning is on, Save opens the same review, titled Review changes before saving, and nothing changes until you select Apply & Save.
What happens to users
| In Entra | In SAFE |
|---|---|
| A user is assigned to the app | Created, with the role from their mapped group or the default role. In Hybrid mode, only emails on your allowed domains are accepted. |
| An assigned user already exists in SAFE with the same email | Entra takes over the user, and their role is set from your mappings. In Hybrid mode this applies only on your allowed domains. |
| A user joins or leaves a mapped group | Their role is recalculated. A user in no mapped group gets the default role. |
| A user is removed from the app or disabled | Suspended. |
| A user is deleted | Deleted. |
| A user's email changes | Not supported. |
Manage the integration
- History. The History tab lists every call Entra made, such as create, update, deactivate and delete, with its result. Filter it or search by email or group.
- Managed Users. The Managed Users tab lists the SAFE users that Entra manages, with their roles.
- Pause syncing. Turn the switch off and confirm Disable. Entra keeps sending changes, and they wait in SAFE until you enable again. Credentials, settings and users stay as they are.
Rotate the client secret
- In SAFE, select Generate Credentials. The client ID stays the same; SAFE adds a second secret, and the current one keeps working.
- Copy the new secret and paste it into Entra's Client Secret field, then select Test Connection and save.
- In SAFE, select Remove Older Secret. Only the newer secret works from then on.
SAFE allows two active secrets, so Generate Credentials is disabled until you remove the older one. Revoke Credentials revokes every active secret, and Entra stops provisioning until you generate new credentials and update Entra.
Troubleshooting
| What you see | What to do |
|---|---|
| Test Connection fails in Entra | Paste the four values again exactly as SAFE shows them, with nothing added to the Tenant URL. If the credentials were revoked or the secret is lost, generate new credentials. |
| The Credentials badge shows Inactive | Entra has not called SAFE in the last two hours, or its latest call failed. Check the Entra provisioning logs and the SAFE History tab. |
| Apply & Enable is disabled in the review | Read the message at the top of the review. Map an Entra group to Admin and make sure you and at least one other active Admin stay Admins. |
| Connector Details shows that the apply failed | Select Retry. SAFE opens the review again with the current data. |
| No groups to choose in Role Mapping | Entra has not synced yet, or the groups are not assigned to the app. Assign them in Entra (Step 5) and wait for the next cycle. |
| Generate Credentials is disabled | Two secrets are active. Update Entra with the newer one, then select Remove Older Secret. |
Did this article help?
Let us know by leaving a star rating at the top of this article.
