Group Mapping for Okta Single Sign-On

Map Okta Groups to Veza roles to enable user management based on Okta group assignments.

Background

Veza can interpret an incoming SAML claim from an identity provider (IdP) to assign federated users to teams and roles based on group assignments in your IdP. If you do not want to create groups in your IdP with the exact naming syntax required by Veza, this document will help you map any group to the expected SAML Attribute Statements.

To enable SAML role assignments when users log in, an administrator will need to do one of the following:

• In Veza, configure Role Mappings to map groups in the incoming SAML claim to Veza roles. Configure the Okta to include a custom attribute that will contain the groups users belong to. See How to Filter Groups with Regex in Okta to configure a group attribute statement on the Veza app integration.

• In Okta, add a custom attribute for Veza app users that will contain their Veza role. Configure the application to include the custom attribute in a SAML groups attribute statement. Then, assign groups to the Veza application and specify the group role in the format {Team SSO Alias}:{role name}.

The instructions in this guide are for the second approach. Use them to map an Okta group (such as a "Veza Administrators" group) to a SAML Attribute Statement Value of Root:admin. Users in this group can log in to Veza with the admin role, without additional configuration of custom role mappings in Veza.

Define an AppUser Custom Attribute on the Veza SAML App

Go to Okta Directory > Profile Editor. Click on the Veza integration app user to edit it and click Add Attribute.

• Data Type: String Array

• Display Name: Veza Role

• Variable Name: role

• Description: Role for users in Veza

• Attribute Type: Group

• Group Priority: Combine values across groups (this is important for users with more than one role. Okta will send all Role Names to Veza rather than only the role mapped to the highest-priority group)

Create a custom attribute in Okta

Add the SAML Attribute Statement on the Veza SAML App

Go to Okta Applications > Applications and click the Veza app integration to view details.

1. In the General tab, scroll down to SAML Settings, and click Edit.

2. In the Configure SAML tab, find the "Attribute Statements (optional)" section

3. Add the attribute statement: Name: groups Name format: Unspecified Value: appuser.role (assuming the AppUser variable name is role)
4. Save the changes.

By default, the SAML Attribute Statement on the Veza SAML App must be named groups. If you must use a name other than groups, you must specify the custom attribute name in the Veza SSO role mapping configuration.

Go to the Assignments Tab and assign your groups

1. Click Assign > Assign to groups and search for the group that will correspond to a Veza role (such as "Veza Administrators").

2. Click Assign and specify the Role attribute with the desired role. The value of the Attribute Statement should be {SSO Alias}:{role name}

Okta users in the chosen group are now assigned to the application with the Role (role) attribute value of Root:admin (or whatever you put in step 2):

Example assignment for Okta user