Configuring a Global Identity Provider

Integrating with an Identity Provider enables single sign on and auto-assignment for Access Reviews.

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 to enable SSO.

• Entity Owners and Resource Manager Tags can be auto-assigned as reviewers.

• Alternate Manager Lookup can be used to assign reviews when you have multiple sources of employee records (e.g., contractors in one system, managers in another).

Typically, your Veza deployment engineer will perform initial IdP settings configuration during onboarding. If further assistance is needed, Veza Support can help through a support ticket.

Administrators with API access can also make these calls directly using endpoints in the private/ namespace. 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

  • Microsoft Azure

  • Custom Identity Provider

• Use Query Builder to search for a user from your identity provider, and retrieve the provider's datasource_id.

• 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

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.

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:

{
  "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.

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:

{
    "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 UID for a provider in the data catalog.
user_identity_property	Unique entity property used to identify the IdP, typically idp_unique_id.
instance_id_property	The user entity property used to identify the IdP instance (e.g. instance_id).
manager_identity_property	The user entity property used to identify the manager.
active_user_conditions	Filter string for identifying inactive users e.g. {"fn": "EQ", "property": "is_active", "value": true}

`user_identity_property` should be a globally unique value. Setting this to a name or email should be avoided as a best practice.

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 <AUTH_PROVIDER_ID> with the id value retrieved from /api/private/auth_providers for your SSO provider.

Okta:

{
  "value": {
    "enabled": true,
    "idp": {
      "auth_provider_id": "<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:

{
  "value": {
    "enabled": true,
    "idp": {
      "auth_provider_id": "<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:

{
  "value": {
    "enabled": true,
    "idp": {
      "auth_provider_id": "<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"
    }
  }
}

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