Entra ID SCIM provisioning

Arbitex supports automatic user and group provisioning via SCIM 2.0 (System for Cross-domain Identity Management). When you connect Microsoft Entra ID as your identity provider, users and groups are synced to Arbitex automatically — no manual account creation, and deprovisioning happens in real time when users are removed in Entra.

Group membership synced via SCIM is what the Policy Engine uses when evaluating user_groups conditions in your policy rules. This means your directory groups become a live enforcement input: add a user to the openai_block group in Entra, and the corresponding policy rule applies to them immediately after the next sync cycle.

sequenceDiagram
    participant Entra as Microsoft Entra ID
    participant SCIM as Arbitex SCIM Endpoint<br/>(api.arbitex.ai/scim/v2)
    participant Platform as Arbitex Platform

    Entra->>SCIM: POST /Users (create user)
    SCIM->>Platform: Provision user account
    Platform-->>SCIM: 201 Created
    SCIM-->>Entra: 201 Created

    Entra->>SCIM: POST /Groups (sync group)
    SCIM->>Platform: Create/update group membership
    Platform-->>SCIM: 200 OK

    Note over Entra,Platform: Incremental sync every 40 minutes

    Entra->>SCIM: PATCH /Users/{id} (active: false)
    SCIM->>Platform: Deactivate user, revoke gateway access
    Platform-->>SCIM: 200 OK

---

Prerequisites

Before you begin, confirm you have:

• An active Microsoft Entra ID tenant with Global Administrator or Application Administrator privileges
• Arbitex admin access — you need Settings > SCIM settings in the Arbitex admin portal
• The SCIM provisioning endpoint URL and bearer token from Arbitex (retrieved in Step 4 below)

---

Step 1: Create the SCIM provisioning application in Entra

1. Sign in to the Microsoft Entra admin center.
2. Navigate to Identity > Applications > Enterprise applications.
3. Select New application.
4. Choose Create your own application.
5. Give the application a name — for example, Arbitex SCIM.
6. Select Integrate any other application you don’t find in the gallery and click Create.

Once created, the application appears in your enterprise applications list.

---

Step 2: Open the provisioning configuration

1. In the new application, select Provisioning from the left sidebar.
2. Set Provisioning Mode to Automatic.
3. This reveals the Admin Credentials section where you configure the SCIM endpoint.

---

Step 3: Configure the SCIM endpoint URL

In the Admin Credentials section:

1. Set Tenant URL to:

   https://api.arbitex.ai/scim/v2

2. Leave Secret Token blank for now — you will fill this in Step 4.

---

Step 4: Retrieve your bearer token from Arbitex

1. In a separate browser tab, sign in to the Arbitex admin portal.
2. Navigate to Settings > SCIM settings.
3. Select Generate SCIM token.
4. Copy the token value — it is shown only once. Store it in a secrets manager.
5. Return to the Entra provisioning configuration.
6. Paste the token into the Secret Token field.
7. Select Test Connection to verify that Entra can reach the Arbitex SCIM endpoint and authenticate successfully.

A success message confirms the endpoint is reachable and the token is valid. If the test fails, confirm the token was copied in full (no trailing whitespace) and that your Arbitex organization has SCIM provisioning enabled.

---

Step 5: Configure user attribute mappings

Arbitex uses the following SCIM user attributes. Verify the mappings in the Attribute Mappings > Provision Microsoft Entra ID Users section:

Entra attribute	SCIM attribute	Required
userPrincipalName	userName	Yes
mail	emails[type eq "work"].value	Yes
givenName	name.givenName	No
surname	name.familyName	No
displayName	displayName	No
accountEnabled	active	Yes

The active mapping is critical. When a user account is disabled in Entra (for example, when an employee offboards), the active: false SCIM update is sent to Arbitex, which immediately revokes their gateway access. This is the primary deprovisioning mechanism.

Remove any attribute mappings not listed above — unmapped attributes are forwarded to Arbitex unchanged and may produce validation errors if they contain unexpected types.

---

Step 6: Configure group provisioning

1. In the Attribute Mappings section, select Provision Microsoft Entra ID Groups.
2. Set Enabled to Yes.
3. Verify the default group attribute mappings:

Entra attribute	SCIM attribute
displayName	displayName
members	members

Group displayName values become the group identifiers used in Arbitex policy rules. For example, if your Entra group is named openai_block, the corresponding user_groups condition in your policy rules should reference "openai_block".

Group names are case-sensitive in policy rule conditions. Use consistent casing in both Entra and your policy configuration.

---

Step 7: Assign users and groups to the provisioning application

SCIM provisioning in Entra only provisions users and groups that are assigned to the application.

1. Navigate to Users and groups in the provisioning application.
2. Select Add user/group.
3. Assign the users or groups you want to provision to Arbitex.

You can assign groups directly — members of an assigned group are automatically included. You do not need to assign every user individually if they are already in an assigned group.

Users who are not assigned to the application are not visible to Arbitex. If a user attempts to authenticate with an Arbitex API key tied to an account that has not been provisioned, the request is rejected with invalid_api_key.

---

Step 8: Test provisioning with a test user

Before enabling provisioning for your full user base, verify the configuration with a single test user:

1. Create a test user in Entra if you do not already have one — for example, scim-test@yourorg.com.
2. Assign the test user to the Arbitex SCIM application.
3. In the Provisioning tab, select Provision on demand.
4. Search for and select your test user, then select Provision.
5. Review the provisioning log. A successful result shows the user created in Arbitex.
6. Sign in to the Arbitex admin portal and navigate to Settings > Users. Confirm the test user appears with the correct userName and group memberships.
7. Disable the test user account in Entra and run Provision on demand again. Confirm the user’s active status updates to false in Arbitex.

---

Step 9: Enable automatic provisioning

Once the test user provisions and deprovisions successfully:

1. In the Provisioning tab, set Provisioning Status to On.
2. Select Save.

Entra begins the initial sync cycle, which provisions all assigned users and groups to Arbitex. Initial sync duration depends on the number of assigned users and groups — allow up to 40 minutes for large directories.

After the initial sync, Entra runs incremental sync cycles every 40 minutes. Changes made in Entra (new users, group membership changes, deactivations) appear in Arbitex within 40 minutes under normal conditions.

---

Troubleshooting

Test connection fails

• Confirm the SCIM endpoint URL is https://api.arbitex.ai/scim/v2 with no trailing slash
• Confirm the bearer token was copied in full — tokens are long and copy errors are common
• Confirm that SCIM provisioning is enabled in your Arbitex organization (Settings > SCIM settings)
• Confirm that your Arbitex admin account has not been suspended or downgraded

Users not appearing in Arbitex after sync

• Confirm the user is assigned to the provisioning application in Entra (Users and groups)
• Run Provision on demand for the specific user to see a detailed provisioning log with any error messages
• Check the provisioning log under Provisioning > Provisioning logs for failure records

Group memberships not syncing

• Confirm group provisioning is enabled (Attribute Mappings > Provision Microsoft Entra ID Groups > Enabled: Yes)
• Confirm the group itself is assigned to the provisioning application — assigning a group only assigns its members for user provisioning; to sync the group object and its membership, the group must also be assigned directly
• Verify the members attribute mapping is present

Users deprovisioned unexpectedly

• Check whether the user was removed from all groups assigned to the application — losing all assigned assignments triggers deprovisioning
• Review the provisioning log for the affected user: the log entry shows the trigger event

SCIM schema validation errors

• These appear in provisioning logs as 400 errors from the Arbitex SCIM endpoint
• The most common cause is attribute mappings that pass Entra attributes that are not in the Arbitex SCIM schema — remove any extra mappings not listed in Step 5

---

See also

• Policy Engine overview — how user_groups conditions reference synced group names
• Policy Rule Reference — the user_groups condition field in detail
• Audit log — user identity in audit entries comes from the provisioned userName