Custom Identity Mappings

Specifying cross-service user relationships during IdP configuration

Overview

Custom Identity Mappings allow you to define relationships between user identities and groups across different systems integrated with Veza. When your organization's access federation doesn't automatically create these connections in Veza, you can specify patterns to map users between systems (for example, connecting an Okta user [email protected] to a SQL Server login DOMAIN\tshaw).

Use custom identity mappings to:

• Connect IdP users (such as Okta users) to local accounts (such as Trino users)

• Connect IdP groups to groups in downstream systems (such as Active Directory Group to Okta Group, or Azure AD Group to GitHub Team)

• Define custom mapping rules for each integration, or use one mapping rule to link IdP identities or groups across multiple connected systems

• Correlate identities in a custom IdP to those in another integrated IdP such as Okta

• Map IdP users to local users in a custom application (as an alternative to using ids)

• Define access-granting relationships for any user or group with the same name, email, or another property in the Veza graph database

• Identify local account ownership using consistent naming patterns

Examples

You can configure mappings for one or more target data sources based on entity attributes or use templates to correlate identities and groups across multiple destination data sources.

User Identity Mapping

1. Active Directory to SQL Server:

   • Source: AD User email [email protected]

   • Destination: SQL Login YOURDOMAIN\admin

   • Configuration: Map email to unique ID, enable "ignore domain"

2. Okta to Custom Application:

   • Source: Okta user email [email protected]

   • Destination: App username jdoe

   • Configuration: Map email to custom property username

Group Identity Mapping

1. Azure AD to GitHub:

   • Source: Azure AD Group Engineering-Team

   • Destination: GitHub Team Engineering Team

   • Configuration: Map name to name, enable "ignore special characters"

2. Okta to Snowflake:

   • Source: Okta Group DataAnalysts

   • Destination: Snowflake Role DATA_ANALYSTS

   • Configuration: Map name to name, apply "UPPER" transformation

3. Multiple Resource Mapping:

   • Source: Active Directory Security Group Finance-Staff

   • Destinations:

     • Salesforce Group Finance Users

     • AWS IAM Group finance-users

     • Box Group Finance Department

   • Configuration: Single mapping configuration applying to multiple destination systems

Prerequisites

Before configuring identity mappings:

• Ensure both the source and destination systems are successfully integrated with Veza

• Verify you have the necessary permissions to modify integration configurations

• Identify the common attributes or patterns used to correlate identities across your systems

Enabling Identity Correlation

To enable custom mappings for an Identity or Cloud Provider:

1. Navigate to the Integrations page

2. Select a cloud or identity provider from the list and click Edit

3. Scroll down to the Mapping Configuration tab

4. Click Add Mapping Configuration

   1. Enable Use Email By Default to automatically create an email-to-email property matcher when no other matchers are configured. Configuring explicit property matchers below will take precedence and this setting will be ignored.

   2. For Mapping Mode, choose Users to create a rule for correlating individual identities. Choose Groups to connect source and destination groups.

   3. For Destination Data Source Type, select the target system for identity mapping

      Identity Mapping for Multiple Resources: If you need to configure identity mappings to many target systems, Veza supports using a single identity mapping configuration to connect users in the IdP to any number of destinations. Contact your Veza support representative to enable this feature. When enabled, you can select more than one Destination Data Source Types from the dropdown menu.

   4. Click Add Property Matcher to create a mapping rule

   5. Under Property Matchers, choose the source system attribute:

      • Email or Unique ID for native integrations like Okta

      • Template for pattern-based matching (see Template Transformations below)

      • Custom Property for OAA template integrations (enter the custom property, e.g. idp_id)

   6. Select the matching destination system property (Email, Unique ID, Template, or Custom)

   7. Configure optional transformations:

      • Ignore Special Characters: Match identities that differ only by special characters (_, -, .)

      • Ignore Domain: Match identities after removing domain portions

5. Add additional property matchers as needed (combined with OR logic)

6. Click Save Configuration

If you configure any property matchers, the Use Email By Default setting is ignored. For example, Use Email By Default is enabled along with a property matcher for username → user_id, Veza will only use the username mapping and ignore the email default setting.

Identity Matchers

Add identity matchers to correlate specific identities that don't meet the conditions of another property matcher:

1. Click Add Identity Matcher to add a mapping rule

2. In the leftmost dropdown, choose a specific identity from the source integration

3. Use the rightmost dropdown to pick the corresponding identity in the destination data source

Template Transformations

Template transformations enable complex identity mapping patterns using property values and transformation functions. This feature is particularly useful when:

• Source and destination systems use different naming conventions

• You need to normalize user identifiers across systems

• You want to define global mapping rules that work across multiple applications

Template Syntax

Templates use property placeholders with optional transformation functions:

{PropertyName | FUNCTION1 | FUNCTION2,...}

For example, to transform a user's name from "JOHN DOE" to "jdoe":

{FirstInitial | LOWER}{LastName | LOWER}

Supported Properties

Templates support the user properties:

• FirstName: User's first name

• LastName: User's last name

• FirstInitial: First character of first name (equivalent to {FirstName | SUB_STRING,0,1})

• LastInitial: First character of last name (equivalent to {LastName | SUB_STRING,0,1})

Transformation Functions

Templates can use transformation functions to map identities based on a partial match or a variation of the source attribute.

SUB_STRING

Extracts a portion of text.

• Parameters:

  • start_index: Starting position (0-based)

  • length: Number of characters to extract

• Example: {FirstName | SUB_STRING,0,3} for "John" returns "Joh"

UPPER

Converts all characters to uppercase.

• Example: {FirstName | UPPER} for "John" returns "JOHN"

LOWER

Converts all characters to lowercase.

• Example: {FirstName | LOWER} for "John" returns "john"

TRIM

Removes leading and trailing whitespace.

• Example: {FirstName | TRIM} for " John " returns "John"

Function Composition

Multiple functions can be chained together, applied left to right:

{FirstName | TRIM | SUB_STRING,0,1 | UPPER}.{LastName | LOWER}

For a user "John Smith", this produces: "J.smith"

Common Template Patterns

Here are some frequently used template patterns:

1. First initial + last name:

   {FirstInitial}{LastName}

   Example: "John Smith" → "jsmith"

2. First name + last initial:

   {FirstName}.{LastInitial}

   Example: "John Smith" → "john.s"

Using OR Logic with Templates

Multiple property matchers can be combined using OR logic. The builder indicates these combinations with "OR" separators. For example:

Template: {FirstName}.{LastName} OR
Template: {FirstInitial}{LastName} OR
Property: email

This configuration would match any of these patterns for a user "John Smith":

• john.smith

• jsmith

• [email protected]

When using templates with multiple property matchers, a match on any single pattern is sufficient to create the identity mapping.

You cannot map an identity provider to itself (for example, between two Okta domains).

Identity Mapping Use Cases

Common combinations for identity mapping include:

Target Systems	Identity Providers
AWS IAM AWS Redshift AWS RDS MySQL AWS RDS Postgres SQL Server Trino Snowflake GitHub Salesforce Box Custom Application (OAA data provider)	Active Directory Azure AD Google Workspace Okta OneLogin AWS Identity Center Custom IDP (OAA identity provider)