SCIM Provisioning with Okta

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

Notes on SCIM Provisioning

Veza supports the following SCIM provisioning features:

When using SCIM provisioning, Veza implements the following critical 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 Okta 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

To enable SCIM provisioning with Okta, you will need:

• Administrator access to both Veza and Okta

• An understanding of your organization's access control requirements

• HTTPS access to your Veza instance

• An Okta version that supports SCIM 2.0

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 Okta

• Okta User names must be the same as the user's email address

• 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 Okta

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 is required for user management.
3. Check your email for "Welcome to Veza.com" and reset the password

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. Configure Okta

1. In your Okta Admin Console, navigate to Applications > Applications

2. Click Create App Integration

3. Select SCIM as the sign-in method

4. Configure the app with the following settings:

   • Base URL: https://TENANT.vezacloud.com/scim/v2

   • Unique identifier field for users: userName

   • Supported provisioning actions:

     • Push New Users

     • Push Profile Updates

     • Push Groups

     • Deactivate Users

   • Authentication Mode: HTTP Header

   • Authorization: Your Veza API key from Step 2 "Create an API Key and enable SCIM provisioning"

4. Configure Group Push and Permissions

To log in to Veza, Okta users must be members of push groups assigned to the Veza application:

1. In Okta:

   • Create or identify the groups that will be used for Veza access

   • Assign users to these groups

   • Navigate to your Veza application

   • Select the Push Groups tab

   • Add the groups you want to provision to Veza

In Veza:

• Verify provisioned groups appear on the Administration > Team Management page

• For each team:

  1. Click on the team to view details

  2. To change roles for a user, click Change Roles in the Actions column.

  3. To change the team scope, click Edit and add or remove providers, then save your changes.

Groups are shown in Veza under the SAML configuration details. Click "Configure" on the Administration > Sign-in Settings page to view the pushed groups:

### 5. Role Management in Okta

When using SCIM provisioning with Veza:

1. You can use your existing Okta groups for provisioning users and teams to Veza.

2. For proper role assignment, ensure the groups pushed through SCIM match the groups configured in your Veza SSO settings:

   • Navigate to Administration > Sign-in Settings in Veza

   • Click "Configure" on your SAML connection

   • Review the "Role Mapping" section to verify your group-to-role mappings
3. To add permissions to teams:

   • Navigate to Administration > Team Management in Veza

   • For each team:

     1. Click on the team to view details

     2. To change roles for a user, click Change Roles in the Actions column

     3. To change the team scope, click Edit and add or remove providers, then save your changes
4. To assign Veza roles directly to individual users using the Roles attribute in Okta:

   1. In Okta Admin Console, navigate to your Veza application

   2. Under Provisioning > To App, click Edit

   3. In the Attribute Mappings section, add the following:

      • Okta Attribute: roles

      • Veza Attribute: roles

   4. Available roles:

      • admin

      • viewer

      • operator

      • scim_provisioner

   Note that direct role assignments can only be set for individual users (not groups).

Validation

1. in Okta, test the connector configuration:

   • Click Test Connector Configuration for the app integration

   • Verify the successful connection:
2. Verify user provisioning:

   • Assign a test user to the Veza application and a pushed group

   • Wait 2-3 minutes for synchronization

   • Confirm the user appears in Veza under Administration > User Management

   • Verify the account's attributes match the Okta user.

3. Verify group provisioning:

   • Confirm Okta groups appear as Teams in Veza

   • Verify that team membership matches the group membership in Okta

   • Test that assigning roles to teams functions as expected

4. Test security boundaries:

   • Attempt to sign in with a deprovisioned user to verify access is properly removed

   • Verify that removing a user from one group but not another maintains appropriate permissions

   • Confirm that users cannot access Veza directly (bypassing SCIM/SAML) once integration is complete

User Deprovisioning

To remove users from Veza:

1. In Okta:

   • Remove the user from all pushed groups

   • Unassign the user from the Veza application

2. In Veza:

   • The user should appear as deactivated

   • The user cannot log in

   • The user's API keys are disabled

To remove groups:

1. In Okta:

   • Remove the group from the SCIM application's Push Groups tab

Troubleshooting

Users or Groups not syncing

• Verify the user is assigned to the Veza application in Okta

• Confirm user is a member of at least one pushed group

• Check user's email matches their username

• Review Okta Dashboard Tasks for provisioning errors

• Review Okta System Log for provisioning errors

• Confirm group push is enabled in the application settings

• In Okta, verify the group is added to the Push Groups tab for the Veza app

API authentication failures

• Verify the API key is correctly copied to Okta

• Confirm that SCIM is enabled on the Veza Sign-in Settings page.

• Ensure your Veza instance is accessible via HTTPS

Getting help

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

• Okta System Log and Dashboard Tasks entries

• Veza error messages

• Timeline of the issue

• Steps to reproduce