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 tom.shaw@veza.com
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:
Active Directory to SQL Server:
Source: AD User email
admin@yourdomain.com
Destination: SQL Login
YOURDOMAIN\admin
Configuration: Map email to unique ID, enable "ignore domain"
Okta to Custom Application:
Source: Okta user email
jane.doe@company.com
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:
Navigate to the Integrations page
Select a cloud or identity provider from the list and click Edit
Scroll down to the Mapping Configuration tab
Click Add Mapping Configurations (available only for supported integrations)
Enable Use Email By Default to automatically map users based on email attributes
For Destination Data Source Type, select the target systems for identity mapping
Click Add Property Matcher to create a mapping rule
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
)
Select the matching destination system property (Email, Unique ID, Template, or Custom)
Configure optional transformations:
Ignore Special Characters: Match identities that differ only by special characters (
_
,-
,.
)Ignore Domain: Match identities after removing domain portions
Add additional property matchers as needed (combined with OR logic)
Click Save Configuration
Identity Matchers
Add identity matchers to correlate specific identities that don't meet the conditions of another property matcher:
Click Add Identity Matcher to add a mapping rule
In the leftmost dropdown, choose a specific identity from the source integration
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:
For example, to transform a user's name from "JOHN DOE" to "jdoe":
Supported Properties
Templates support the user properties:
FirstName
: User's first nameLastName
: User's last nameFirstInitial
: 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:
For a user "John Smith", this produces: "J.smith"
Common Template Patterns
Here are some frequently used template patterns:
First initial + last name:
Example: "John Smith" → "jsmith"
First name + last initial:
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:
This configuration would match any of these patterns for a user "John Smith":
john.smith
jsmith
john.smith@company.com
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:
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)
Last updated
Was this helpful?