> 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/features/access-reviews/configuration/global-idp-settings.md). # Configuring a Global Identity Provider Integrating with an Identity Provider enables single sign on and auto-assignment for Access Reviews. ### Overview For organizations with many users and access reviewers, enabling a global Identity Provider (IdP) eliminates the need to manually specify additional reviewers by email, or create additional Veza user accounts for reviewers. When enabled: * Administrators and Operators can create reviews and assign reviews for any IdP user in a domain. * Any IdP user able to log in to Veza with single sign-on (SSO) can authenticate without the need to provision an account beforehand. See [Sign-In Settings](/4yItIzMvkpAvMVFAamTf/administration/administration/sign-in-settings.md) to enable SSO. * [Entity Owners and Resource Manager Tags](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/managers-and-resource-owners.md) can be auto-assigned as reviewers. * [Alternate Manager Lookup](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings/alternate-manager-lookup.md) can be used to assign reviews when you have multiple sources of employee records (e.g., contractors in one system, managers in another). Configure a Global IdP in the Veza UI, which previews the mapping before you save it. The API remains available for earlier releases and for alternate manager lookups, which have no UI. Your Veza deployment engineer typically performs the initial configuration during onboarding. For further assistance, open a ticket with Veza Support. A tenant has one Global IdP configuration. Saving a new configuration replaces the existing one. ### Configure in the Veza UI **Available in Veza v2026.9.21 and later.** On earlier releases, use the API described in [Configure with the API](#configure-with-the-api). You need an integrated identity provider in the Access Graph and the correct `auth_provider_id` before you start. See [Before you start](#before-you-start). The page also requires at least one enabled SAML or SSO authentication provider. Without one, the page shows **This feature requires a configured IdP** and no **Configure** button. 1. Open **Administration** > **Global IdP Settings**. 2. Select **Configure**. If a configuration already exists, select the edit icon on the **IdP Settings** card instead. 3. Complete the fields, then select **Continue**: * **User type**: the graph entity type to search for users, such as `OktaUser` or `CustomIDPUser`. * **Auth Provider**: the single sign-on provider these users authenticate with. Required when **User type** is `CustomIDPUser`. Otherwise, the field is optional, and you can leave it blank if you are unsure. * **Instance UID**: the UID for the provider in the data catalog. * **User Identity Property**: the property that uniquely identifies each IdP user. * **Instance Identity Property**: the property that identifies the IdP instance. * **Manager Identity Property**: the property that holds a user's manager. 4. Review the **Preview IdP mapping** step, then select **Confirm** to save. The property fields offer the properties defined on the entity type you selected, so choose **User type** first. The wizard does not set `active_user_conditions` or `case_insensitive_match`. Editing a mapping in the UI keeps their existing values. To change them, use the API. {% hint style="info" %} Only users with the **Administrator** role on the root team can open this page and configure a mapping. For all other roles, the page does not appear in the navigation. See [Roles](/4yItIzMvkpAvMVFAamTf/administration/administration/users/roles.md). Alternate manager lookups have no UI and are available only through the API. See [Alternate Manager Lookup](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings/alternate-manager-lookup.md). {% endhint %} #### Preview the mapping before saving The second step of the wizard, **Preview IdP mapping**, runs the proposed configuration without saving it and lists the results in three columns: | Column | What it shows | | ------------- | -------------------------------------------------------------------------------------- | | **IdP user** | The identity matched in the identity provider you configured. | | **Veza user** | The Veza users that identity maps to, separated by commas when there is more than one. | | **Manager** | The managers resolved for that user, separated by commas when there is more than one. | Use the search box to check a specific user by exact email address. An empty **Manager** column means manager auto-assignment does not resolve for that user. The most common cause is a manager reference that does not match any value of the **User Identity Property** you configured. See [Alternate Manager Lookup](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings/alternate-manager-lookup.md) for how manager references resolve. The preview lists every value of a list-valued **Manager Identity Property**, but reviewer auto-assignment uses only the first. More than one manager in the preview can indicate a misconfigured mapping. {% hint style="warning" %} The preview covers only users who have signed in to Veza. A user who has not signed in is absent from the list, whether or not the mapping would resolve that user. {% endhint %} ### Configure with the API Use the API on releases earlier than v2026.9.21, or to configure alternate manager lookups. Otherwise, use the [Veza UI](#configure-in-the-veza-ui), which previews the mapping before you save it. Administrators with API access can call these endpoints in the `private/` namespace. APIs in the `private` namespace are subject to change as features are added or modified. See the following sections for prerequisites and API request format. #### Before you start * The Access Graph must contain entities for an integrated provider data source. See the integration guides for: * [Okta](/4yItIzMvkpAvMVFAamTf/integrations/integrations/okta.md) * [Microsoft Azure](/4yItIzMvkpAvMVFAamTf/integrations/integrations/azure.md) * [Custom Identity Provider](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-identity-provider-template.md) * Find the correct `instance_id` value by opening any user node from your identity provider in the Graph and copying the `Datasource Id` property shown in the Graph Node Details panel. * Single Sign-On must be enabled to allow external users to log in to Veza. * You must retrieve the correct `auth_provider_id` for your SSO provider (see instructions below). **Retrieving the auth\_provider\_id** {% hint style="warning" %} **Important**: The `auth_provider_id` in your IdP settings must match the `id` field from `/api/private/auth_providers` for your SSO provider type. Using a mismatched auth provider ID will cause duplicate users to appear in Access Reviews—both the local user and the graph user will be shown when only the graph user should appear. {% endhint %} Your Veza support representative can help retrieve the `auth_provider_id`. Alternatively, you can retrieve it directly with the following API calls: **GET** `/api/private/auth_providers` This will return a list of all configured authentication providers. To find the correct value: 1. Identify which authentication provider your users use to log in to Veza: * **If using SAML**: Find the entry with `"auth_provider_type": "SAML_AUTH_PROVIDER"` and `"enabled": true` * **If using OIDC**: Find the entry with `"auth_provider_type": "SSO_AUTH_PROVIDER"`, `"auth_provider_implementation": "OIDC"`, and `"enabled": true` 2. Use the `id` field from that entry as your `auth_provider_id` Example response excerpt for a SAML provider: ```json { "auth_providers": [ { "id": "2017389d-a2e1-4849-a596-c1a1bd308fbc", "auth_provider_type": "SAML_AUTH_PROVIDER", "enabled": true, "name": "SAML SSO" } ] } ``` In this example, the `auth_provider_id` would be `2017389d-a2e1-4849-a596-c1a1bd308fbc`. You can also check the current Global IdP settings: **GET** `/api/private/workflows/access/global_settings/idp_settings` Note: These endpoints require an administrator API key to access. For detailed API endpoint documentation including request examples, see [alternate-manager-lookup.md](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings/alternate-manager-lookup.md#api-configuration). #### Update global identity provider settings request **PUT** `/api/private/workflows/access/global_settings/idp_settings` Enable Veza to suggest reviewers from the graph by specifying the SSO `auth_provider_id` and identity provider data source `instance_id`. {% hint style="warning" %} Keep the outer `value` wrapper shown below. A `PUT` that sends the settings object directly, without the wrapper, returns `200 OK` and clears the existing Global IdP configuration instead of updating it. {% endhint %} ```json { "value": { "enabled": true, "idp": { "auth_provider_id": "cf9bab40-4e48-4afc-a310-acfdad416233", "user_type": "OktaUser", "instance_id": "dev-5150036.okta.com", "user_identity_property": "idp_unique_id", "instance_id_property": "datasource_id", "manager_identity_property": "manager_idp_unique_id" } } } ``` | Value to update | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | Set `true` to enable the provider as a Global IdP. | | `auth_provider_id` | Internal UID for the single sign-on provider instance. This must match the `id` field from `/api/private/auth_providers` for your SSO provider type. | | `user_type` | Graph entity type to search for users, such as `CustomIDPUser` or `OktaUser`. | | `instance_id` | The value used to scope identity lookups to a specific data source. This must match the `datasource_id` property on user nodes in the graph. To find this value, open any user node from your identity provider in the Graph and copy the `Datasource Id` property value shown in the Graph Node Details panel. | | `user_identity_property` | Unique entity property used to identify the IdP user, typically `idp_unique_id`. | | `instance_id_property` | The user entity property used to identify the IdP instance (typically `datasource_id`). | | `manager_identity_property` | The user entity property used to identify the manager. | | `idp_type` | Type descriptor for the identity provider, such as `okta` or `azure_ad`. | | `active_user_conditions` | Optional array of conditions that limit which users appear in the list you choose from when you assign a reviewer manually. It does not affect how Veza finds a user's manager. | | `case_insensitive_match` | When `true`, the mapping preview matches manager identity property values regardless of case. Automatic reviewer assignment does not use this setting and matches the value case-sensitively, so a manager whose value differs only in case is not assigned. Defaults to `false`. | `idp_type` is required when `user_type` is `CustomIDPUser`: set it to the `idp_type` defined for that custom provider. Always send `active_user_conditions` as an array, even for a single condition, as in `[{"fn": "EQ", "property": "is_active", "value": true}]`. There is no not-equal function: negate a condition with `"not": true`. Whenever the request includes `idp`, the three property names (`user_identity_property`, `instance_id_property`, and `manager_identity_property`) are all required and must be lowercase snake\_case; an empty or omitted value returns `400`. The same rule applies to the property names on each entry in `alternate_manager_lookup_settings`. {% hint style="warning" %} This request replaces the whole configuration, including any alternate manager lookups. A `PUT` that sets `idp` but omits `alternate_manager_lookup_settings` removes the alternate lookups. Send the full settings object each time. See [Alternate Manager Lookup](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings/alternate-manager-lookup.md). {% endhint %} {% hint style="warning" %} \`user\_identity\_property\` should be a globally unique value. Setting this to a name or email should be avoided as a best practice. {% endhint %} Notes: * `auth_provider_id` identifies users with entries in the local user database and will also map correlated graph entities. * There can be several instances of an identity provider for a given `user_type`. * `instance_id` ensures the user info is pulled from the correct instance and domain. * Veza will populate the user list by searching for nodes of type `user_type` with `instance_id_property` equal to `instance_id`. * Setting `"instance_id_property": "datasource_id"` will typically achieve the correct behavior. #### Examples Replace `` with the `id` value retrieved from `/api/private/auth_providers` for your SSO provider. Okta: ```json { "value": { "enabled": true, "idp": { "auth_provider_id": "", "user_type": "OktaUser", "instance_id": "dev-5150036.okta.com", "user_identity_property": "idp_unique_id", "instance_id_property": "datasource_id", "manager_identity_property": "manager_idp_unique_id" } } } ``` Microsoft Azure AD: ```json { "value": { "enabled": true, "idp": { "auth_provider_id": "", "user_type": "AzureADUser", "instance_id": "d5d23474-d857-4e12-bf68-75d638867e93", "user_identity_property": "idp_unique_id", "instance_id_property": "datasource_id", "manager_identity_property": "manager_idp_unique_id" } } } ``` Custom Identity Provider. `idp_type` is required when `user_type` is `CustomIDPUser`: ```json { "value": { "enabled": true, "idp": { "auth_provider_id": "", "user_type": "CustomIDPUser", "instance_id": "aa650cf7-2370-406e-bb35-1a8e14b92919", "user_identity_property": "idp_unique_id", "instance_id_property": "datasource_id", "manager_identity_property": "manager_idp_unique_id", "idp_type": "custom_idp" } } } ``` #### SSO External ID Integration When your SSO provider doesn't guarantee unique email addresses across your organization, Access Reviews can use a configurable external ID from your SSO authentication to reliably match users for reviewer assignment and auto-assignment features. This integration requires coordination between your SSO attribute mapping configuration and the Global IdP settings described above. The key relationship is between the **SSO external ID** configured in your SAML or OIDC attribute mapping and the **`user_identity_property`** setting in your Global IdP configuration. These values must contain matching data for users to be correctly identified during Access Reviews operations. For example, if your Okta integration uses `idp_unique_id` as the `user_identity_property` (sourced from Okta's login field), you would configure your SSO external ID mapping to read from the `login` attribute in your SSO provider claims, since both properties contain the same unique identifier values for each user. This alignment enables Access Reviews to: * Reliably match SSO authenticated users with their corresponding graph entities during reviewer assignment * Auto-assign managers and resource owners based on graph metadata, even when email addresses are not unique * Maintain consistent user identification across SSO authentication and Access Reviews workflows To configure SSO external ID for Access Reviews integration, see the SSO attribute mapping documentation for your authentication method. The external ID configuration is part of your SSO setup and works automatically with existing Global IdP settings once properly aligned. #### Validating global identity provider settings Test your configuration by creating a review and selecting reviewers: * If the `user_type`, `instance_id`, and `instance_id_property` are correct, identities from the graph will appear in the suggestions. * If `auth_provider_id` is correct, SSO users should only appear once in the scenario above. The local user entry is filtered from the list. Only the user record from the graph entity will appear. **Testing SSO External ID Integration** When SSO external ID is configured, you can verify the precedence hierarchy and fallback behavior: **Precedence Verification**: Create a test user with both email and external ID values in your SSO provider. When this user authenticates to Veza and appears in reviewer assignment, the system will use their external ID for Access Reviews user matching, taking priority over email-based matching. **Fallback Testing**: Configure a test user with email but no external ID value in your SSO provider claims. This user should still authenticate successfully and be available for reviewer assignment, demonstrating that missing external ID values automatically fall back to email-based matching without authentication failures. **Configuration Alignment**: Verify that the external ID values from your SSO provider match the data in your `user_identity_property` field for graph entities. Users should be consistently matched between SSO authentication and reviewer assignment, enabling reliable auto-assignment features even when email addresses are not unique in your SSO provider. **Expected behavior when configured correctly:** * Identities from the graph appear in reviewer suggestions (validates `user_type`, `instance_id`, `instance_id_property`) * Each SSO user appears **only once** as their graph entity (validates `auth_provider_id`) **If you see duplicate users** (both local user and graph user for the same person): * The `auth_provider_id` does not match your SSO provider's ID * Retrieve the correct value from `/api/private/auth_providers` and update your configuration --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.