> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/scim/entra-id.md).

# SCIM Provisioning with Microsoft Entra ID

This guide explains how to configure Microsoft Entra ID as your identity provider (IdP) for automated user provisioning with Veza. Following these steps will establish a connection between Entra ID and Veza for managing the complete user lifecycle, including account provisioning and deprovisioning.

#### Notes on SCIM Provisioning

Veza supports the following SCIM provisioning features:

| Feature              | Description                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| Push New Users       | Users assigned to the Veza application in Entra ID are automatically created in Veza           |
| Push Profile Updates | Profile changes in Entra ID are automatically updated in Veza                                  |
| Push Groups          | Groups assigned to the Veza application in Entra ID are automatically created as Teams in Veza |
| Deactivate Users     | Removing users from the Veza application in Entra ID automatically deactivates them in Veza    |
| Reactivate Users     | Reassigning previously deactivated users in Entra ID reactivates them in Veza                  |

When using SCIM provisioning, Veza implements the following security behaviors that administrators should understand:

**SCIM with SAML SSO**: When SCIM provisioning is enabled in Veza **Sign-In Settings**, Veza no longer synchronizes user profiles during SAML logins (SAML JIT and SAML metadata sync is disabled).

**Group-to-Role Mapping Behavior**: Each unique push group from Entra ID is mapped to one or more team/role assignments in Veza. When a user is provisioned or their group membership changes, this role mapping is automatically applied to create or update the corresponding team/role assignments.

**Permission Persistence**: Users can receive the same permission from multiple IdP groups. Veza preserves permissions until all sources are removed. For example, if a user belongs to two different IdP groups that both assign Root/Admin roles in Veza, removing the user from only one of these groups will not revoke their Root/Admin permissions. The user will retain these permissions until removed from all groups granting access.

### Prerequisites

{% hint style="warning" %}
Ensure you maintain at least one local admin account on the root team as a break glass account. This account provides access if there are issues with your identity provider connection.
{% endhint %}

To enable SCIM provisioning with Entra ID, you will need:

* A Microsoft Entra subscription with permission to create enterprise applications
* **Entra ID SAML SSO with Veza already configured.** SCIM provisioning requires a SAML auth provider connection in Veza. See [Single Sign-On with Microsoft Entra](/4yItIzMvkpAvMVFAamTf/administration/administration/sign-in-settings/saml/saml-entra.md) for setup instructions. Note: SCIM provisioning uses a separate non-gallery enterprise application in Entra ID; keep your existing SSO application in place.
* Administrator access to Veza
* HTTPS access to your Veza instance

You will need a dedicated local admin user in Veza for SCIM configuration, created during setup.

Important considerations:

* At least one admin user must exist on the root team (break glass account)
* Once SCIM is enabled, all user management must be performed through Entra ID
* **`userName` must match the user's primary email address.** Veza validates that the SCIM `userName` and the primary `emails` value are identical. Configure Entra ID to send `userName` as the user's email address. If your organization's `userPrincipalName` values are not in email format, map `userName` to `mail` instead.
* Queries are limited to returning a maximum of 200 items at a time
* Veza creates Teams from groups provisioned through SCIM. Permissions are managed by assigning roles to teams provisioned in Veza.

### Enabling SCIM Provisioning with Entra ID

#### 1. Create a SCIM Admin User in Veza

1. Go to **Administration** > **User Management** and create a new Veza user.
2. Assign the user to the root team with the following roles:
   * **Admin** or **Operator** is required to log in and create a personal API key. This role can be revoked after the API key is obtained.
   * **SCIM Provisioner** is required to access Veza SCIM endpoints.

     ![Creating a SCIM admin account in Veza.](/files/rYyUIjyuL6Twsfqzmno4)
3. Check your email for "Welcome to Veza.com" and reset the password.

See [User Management](/4yItIzMvkpAvMVFAamTf/administration/administration/users.md) for more on adding local user accounts to Veza.

#### 2. Create an API Key and enable SCIM provisioning

1. Sign in as the newly created SCIM admin user.
2. Navigate to **Administration** > **API Keys**.
3. Create a new API key:
   * This is a personal API key for the SCIM admin user.
   * Save this key securely using your organization's secrets management process; this key has administrative access to your Veza instance.
   * The key cannot be retrieved after creation.
4. Go to **Administration** > **Sign-in Settings**.
5. Scroll down and check the box to **Enable SCIM provisioning**.
   * Note: There is a 30-second delay before endpoints become available.

#### 3. Create a new enterprise application for SCIM provisioning

{% hint style="warning" %}
The Veza application in the Microsoft Entra gallery is outdated and does not include SCIM provisioning support. Do not use the gallery app for this step. Create a new, non-gallery enterprise application as described below.
{% endhint %}

1. In the Microsoft Entra admin center, go to **Entra ID** > **Enterprise applications**.
2. Click **New application**, then select **Create your own application**.
3. Enter a name (for example, "Veza SCIM"), select **Integrate any other application you don't find in the gallery**, and click **Create**.
4. In the new application, select **Provisioning** from the left menu.
5. Set **Provisioning Mode** to **Automatic**.
6. Expand **Admin Credentials** and configure the following:
   * **Tenant URL**: `https://{tenant}.vezacloud.com/scim/v2`
   * **Secret Token**: The Veza API key from step 2
7. Click **Test Connection**. A success message confirms that Entra ID can reach the Veza SCIM endpoint with the provided credentials.

#### 4. Configure provisioning scope and attribute mappings

1. Under **Settings**, set **Scope** to **Sync only assigned users and groups**. This limits provisioning to users and groups explicitly assigned to the application, avoiding unintended account creation.
2. Expand **Mappings** and open the **Provision Microsoft Entra ID Users** mapping.
3. Review the attribute mappings. The following attributes are required:

   | Entra attribute     | SCIM attribute                 | Notes                                    |
   | ------------------- | ------------------------------ | ---------------------------------------- |
   | `userPrincipalName` | `userName`                     | Must resolve to the user's email address |
   | `mail`              | `emails[type eq "work"].value` | Primary email; must match `userName`     |
   | `givenName`         | `name.givenName`               | Required                                 |
   | `surname`           | `name.familyName`              | Required                                 |
   | `IsSoftDeleted`     | `active`                       | Controls account deactivation            |

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Veza requires that <code>userName</code> and the user's primary email address are the same value. If your organization's <code>userPrincipalName</code> is not in email format, update the mapping so that <code>userName</code> maps to <code>mail</code> instead. Provisioning will fail for any user where these values differ.</p></div>
4. Do not enable enterprise extension attribute mappings. Veza's SCIM implementation supports only core SCIM 2.0 attributes.

#### 5. Assign users and groups, and start provisioning

1. In the application, select **Users and groups**.
2. Add the Entra ID groups and users to provision to Veza.
3. Return to **Provisioning** and set **Provisioning Status** to **On**, then save.

{% hint style="info" %}
Users must be both assigned to the application and members of an assigned group to be provisioned successfully and able to log in.
{% endhint %}

After enabling provisioning, Entra ID runs an initial sync cycle immediately, then syncs on a 40-minute interval. See [How provisioning works](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works) for more details on the provisioning cycle.

### Role management

Groups provisioned via SCIM appear as Teams in Veza under **Administration** > **Team Management**. Groups do not automatically carry Veza role assignments; you must configure role mappings in Veza separately.

To assign roles to provisioned groups:

1. In Veza, navigate to **Administration** > **Sign-in Settings**.
2. Click **Configure** on your SAML connection.
3. In the **Role Mapping** section, add a mapping for each Entra ID group that should receive a Veza role.

See [Role Mapping for Single Sign-On](/4yItIzMvkpAvMVFAamTf/administration/administration/sign-in-settings/sso-feature-role-mapping.md) and [Teams](/4yItIzMvkpAvMVFAamTf/administration/administration/users/teams.md) for more information.

### Validation

1. In Entra ID, go to **Provisioning** > **Provision on demand**, select a test user, and run a provisioning cycle.
2. Review **Provisioning logs** for success or error details.
3. In Veza, verify the test user appears under **Administration** > **User Management** with the correct name and email address.
4. Verify Entra ID groups appear as Teams under **Administration** > **Team Management**.
5. Verify team membership matches the group membership in Entra ID.
6. Test deprovisioning: unassign a test user from the application in Entra ID, wait for the next provisioning cycle, and confirm the account is deactivated in Veza.

### User deprovisioning

To remove users from Veza:

1. In Entra ID:
   * Unassign the user from the Veza application, or disable or delete the account.
2. In Veza:
   * The user will appear as deactivated.
   * The user cannot log in.
   * The user's API keys are disabled.

To remove groups:

1. In Entra ID:
   * Remove the group assignment from the application.

### Troubleshooting

#### Users not syncing

* Check **Provisioning logs** in Entra ID for specific error messages on each user.
* Verify the user is assigned to the application and is a member of an assigned group.
* Confirm that `userName` maps to the user's email address. This is the most common provisioning rejection.
* Confirm SCIM provisioning is enabled in Veza under **Administration** > **Sign-in Settings**.

#### "userName and email must be the same" error

Entra ID is sending a `userPrincipalName` that is not in email format. Update the Entra ID attribute mapping to send `mail` as `userName` instead of `userPrincipalName`.

#### Profile update errors

Entra ID may send a PATCH operation updating the `displayName` attribute during profile sync. Veza does not support patching `displayName` directly and returns a 400 error for this operation. Veza derives the display name from `givenName` and `familyName`. To prevent this, remove any `displayName` attribute mapping from the **Provision Microsoft Entra ID Users** mapping in Entra ID.

#### Authentication failures

* Verify the API key was copied correctly into the **Secret Token** field.
* Confirm the SCIM admin user's API key has not expired or been revoked.
* Ensure your Veza instance is accessible via HTTPS.

#### Getting help

For additional assistance, contact Veza Support and provide the following information if available:

* Entra ID provisioning logs
* Veza error messages
* Timeline of the issue
* Steps to reproduce


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/scim/entra-id.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.