Custom Identity Mappings

Specifying cross-service user relationships during IdP configuration

Overview

Custom Identity Mappings allow you to define relationships between user identities across different systems integrated with Veza. When your organization's access federation doesn't automatically create these connections, you can specify patterns to map users between systems (for example, connecting an Okta user [e-mail] 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)

• 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 entities with the same name, email, or another property in the Veza graph database

• Associate users in your identity provider with any application where Veza does not natively support cross-service connections

• Identify local account ownership using consistent naming patterns

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

1. Active Directory to SQL Server:

   • Source: AD User email [e-mail]

   • Destination: SQL Login YOURDOMAIN\admin

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

2. Okta to Custom Application:

   • Source: Okta user email [e-mail]

   • Destination: App username jdoe

   • Configuration: Map email to custom property username

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 Configurations (available only for supported integrations)

   1. Enable Use Email By Default to automatically map users based on email attributes

   2. For Destination Data Source Type, select the target systems for identity mapping

   3. Click Add Property Matcher to create a mapping rule

   4. 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 for OAA template integrations (enter the custom property, e.g. idp_id)
   5. Select the matching destination system property (Email, Unique ID, Template, or Custom)

   6. 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

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 builer 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

• [e-mail]

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

Currently, identity mapping only supports user entities. Group relationships cannot be mapped. Additionally, you cannot map an identity provider to itself (for example, between two Okta domains).

Identity Mapping Use Cases

Common combinations for identity mapping include:

Local Users	Identity Providers
AWS IAM AWS Redshift AWS RDS MySQL AWS RDS Postgres SQL Server Trino Snowflake Custom Application (OAA data provider)	Active Directory Azure Google Workspace Okta OneLogin AWS Identity Center Custom IDP (OAA identity provider)