> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/configuration/automatic-identity-matching.md).

# Automatic Identity Matching

### Overview

Veza connects the accounts a person holds in individual systems to their identity in your identity provider, so that access to an application resolves back to a person. Veza establishes these connections two ways:

* **Automatic matching**, described on this page. Veza compares a fixed set of attributes and creates the relationship with no configuration.
* [**Identity mappings**](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md), which you configure on an integration when the values you want to correlate are not among the attributes compared automatically.

Read this page first. Automatic matching covers most environments, and configuring a mapping that duplicates it adds no relationships.

### How automatic matching works

Every local account that Veza can correlate carries one or more **identity values**. For an application, these values live in the `identities` attribute of the local user. Where those values come from depends on how the application reaches Veza, described in [Where identity values come from](#where-identity-values-come-from).

For each extracted identity provider, Veza assembles a lookup of the attribute values that can identify its users and groups. The attributes in that lookup are fixed per provider and are listed in [Attributes compared on the identity provider](#attributes-compared-on-the-identity-provider).

Veza then compares each of the account's identity values against that lookup. A value that matches any attribute in the lookup creates an identity relationship between the identity provider user and the local account.

Two properties of the comparison matter in practice:

* **The comparison is a whole-string match, and it ignores case.** `Jane.Doe@company.com` and `jane.doe@company.com` are equivalent.
* **Nothing else is normalized.** Veza does not strip domains, ignore punctuation, or trim surrounding whitespace during automatic matching. A value of `jdoe` does not match `jdoe@company.com`, and a trailing space prevents a match. Those tolerances are available only in a [configured mapping](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md#property-matchers).

Users and groups occupy the same lookup. An identity value that equals the name of an identity provider group correlates the account to that group rather than to a user, which is intended for applications whose local groups mirror identity provider groups.

Both integrations must complete an extraction before a relationship can appear. Correlation runs at the end of an extraction, and both the application and the identity provider trigger it, so relationships appear after whichever side extracts next. Values that match nothing are not treated as failures: an OAA push returns them as warnings, the local user is still created, and no relationship appears.

### Attributes compared on the identity provider

The attribute names below are the ones shown on the user entity in Veza. Where an attribute duplicates another, that is noted, because it changes which source values can match.

#### Okta

* User Login
* IdP Unique ID, which for Okta holds the login
* Email

For groups, Veza compares the group name and IdP Unique ID.

Veza does not compare Okta Employee ID, Second Email, or Okta profile custom attributes.

#### Entra ID (Azure AD)

* Principal Name, the user principal name (UPN)
* On-Premises SAM Account Name
* IdP Unique ID, which for Entra ID holds the UPN
* Email

For groups, Veza compares Principal Name, group name, the group's object ID, and IdP Unique ID, which for an Entra ID group holds the group's email address rather than its principal name.

Veza does not compare Employee ID, Other Mails, or Proxy Addresses.

#### Active Directory

* IdP Unique ID, which for Active Directory holds the userPrincipalName
* Account Name, the sAMAccountName
* Distinguished Name
* Email

For groups, Veza compares the group name and Distinguished Name.

Veza does not compare Employee ID, Employee Number, objectGUID, or SID.

#### OneLogin

* IdP Unique ID
* Email

#### Google Workspace

* Name and IdP Unique ID, both of which hold the primary email address

Google Workspace has no separate email comparison, and **email aliases are not compared**. An account whose identity value is a Google Workspace alias does not correlate automatically.

#### Custom identity providers

For a [custom identity provider](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-identity-provider-template.md) built with OAA, Veza compares:

* IdP Unique ID, which holds the `identity` value from the payload
* Email

#### Providers without automatic matching

PingOne, PingFederate, and CyberArk Identity are not available for automatic matching to OAA applications, custom principals, or HRIS employees. Correlate them with a [configured mapping](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md). CyberArk Identity does correlate automatically to Entra ID and Active Directory, described in [Automatic correlation in other integrations](#automatic-correlation-in-other-integrations).

### Where identity values come from

#### Custom applications submitted through the API

Veza compares the values in the local user's `identities` array. The local user's `email` attribute is stored for display and is not compared, so populate `identities` even when the same address is already in `email`. See [Cross-service connections](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/cross-service-connections.md).

#### CSV upload without column mapping

Veza uses the email column as the identity value automatically.

#### CSV upload with column mapping

Veza uses either of these, and both feed the same `identities` attribute:

* The **Identity** field in the Application template configuration, which takes a comma-separated list of column names, such as `email` or `email,username`.
* A column mapped to the local user **Identities** attribute in the column mapper.

Mapping a column to the local user **Email** attribute does not correlate the user. Email populates a display attribute only. See [CSV upload](/4yItIzMvkpAvMVFAamTf/integrations/integrations/csv.md#identity-mapping).

#### Applications collected by a built-in OAA connector

The connector decides which value it submits. Atlassian Cloud, for example, submits the user's email address. To confirm what a given integration submits, open a local user in Veza and read its Identities attribute.

#### HRIS employees

Veza resolves one identity value per employee, taking the first of these that has a value:

1. `idp_id`
2. `email`
3. `employee_number`

Veza then compares that single value against the identity provider lookup above. An employee number therefore correlates only when the identity provider login, UPN, or email address is itself that employee number. Veza does not compare an employee number to an Okta or Active Directory Employee ID attribute. This applies to HRIS data from any source: the [HRIS template](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/hris-template.md), CSV upload, [Database HRIS](/4yItIzMvkpAvMVFAamTf/integrations/integrations/database-hris.md), and native HRIS integrations.

#### Custom identity providers

A custom identity provider user correlates to a user in another provider through its `source_identity` and `source_identity_type` attributes rather than through an identity value comparison. See [Custom Identity Provider template](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-identity-provider-template.md#source-identity-assignments).

### How many relationships a match creates

* For a local user in a **custom application**, Veza uses the first identity value that matches and creates one relationship. Listing several identity values gives Veza alternatives to try, not several relationships.
* For a local user in a **custom principal**, which is the template behind connectors such as Atlassian Cloud, every match creates a relationship. One account can correlate to identities in more than one identity provider.

When two identity provider users share a compared value, such as a shared mailbox address, only one of them stays in the lookup and the account correlates to that one. Keep the values you rely on unique to each user.

### Attributes not compared automatically

* Employee ID and Employee Number, unless the value happens to also be the login, UPN, or email address
* Okta Second Email, Entra ID Other Mails and Proxy Addresses, Google Workspace aliases
* objectGUID and SID
* Any custom property or tag on either side

{% hint style="warning" %}
Automatic matching compares only the attributes listed on this page. It is not a search across every attribute on the identity provider profile. Holding the same Employee ID on both sides does not correlate two accounts.

To correlate on any attribute outside the lists above, configure an identity mapping with a **Property** or **Custom Property** matcher. See [Custom Identity Mappings](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md).
{% endhint %}

### Automatic matching between identity providers

Veza correlates the users and groups of these provider pairs without configuration:

* **Active Directory and Entra ID.** For users, the Entra ID `onPremisesUserPrincipalName` matches the Active Directory user principal name. For groups, `onPremisesDistinguishedName` matches the Active Directory distinguished name. Veza checks the `on_premises_sync` attribute first, from the Microsoft Graph `onPremisesSyncEnabled` field, and correlates only entities where it is `true`.
* **Okta and Google Workspace.** The Okta app user email matches the Google Workspace user email. The email domains must match.

These two pairs are the only ones where configuring an identity mapping replaces the automatic behavior. For every other pair, a configured mapping adds its own relationships alongside anything matched automatically.

### Automatic correlation in other integrations

Several integrations correlate their local accounts to identity provider users on their own, using a value specific to that integration:

* **CyberArk Identity.** Entra ID Principal Name matches the CyberArk `login_name`; Active Directory Distinguished Name matches the CyberArk `idp_unique_id`. See [CyberArk](/4yItIzMvkpAvMVFAamTf/integrations/integrations/cyberark.md#identity-mapping).
* **GitHub.** Veza correlates GitHub user accounts to Okta and Entra ID identities. See [GitHub](/4yItIzMvkpAvMVFAamTf/integrations/integrations/github.md).
* **GitLab.** Veza correlates GitLab users to any integrated identity provider by email address. See [GitLab](/4yItIzMvkpAvMVFAamTf/integrations/integrations/gitlab.md).
* **Databricks.** Veza correlates workspace users through the single sign-on identifier. See [Databricks](/4yItIzMvkpAvMVFAamTf/integrations/integrations/databricks-single-workspace.md).
* **Okta and AWS.** Veza recognizes the relationship established by the AWS Account Federation application in Okta. See [Okta](/4yItIzMvkpAvMVFAamTf/integrations/integrations/okta.md).

Where an integration already correlates automatically, property matchers for the same pair are redundant.

### Example: a match when email addresses differ

An Atlassian Cloud principal user has the email address `amishra@example.com`, submitted by the connector as its identity value. The corresponding Entra ID user has a different value in Email, but its Principal Name, and therefore its IdP Unique ID, is `amishra@example.com`.

Veza correlates the two accounts. The match is made on Principal Name, not on Email, which is why the two Email attributes can differ and the relationship is still correct.

### When accounts do not correlate

Work through these in order:

1. Open the local user in Veza and confirm the Identities attribute holds a value. An empty Identities attribute is the most common cause, and populating Email alone does not correlate the user.
2. Compare that value to the attributes listed for your identity provider above. Check for a domain on one side only, a display name where a login is expected, and differences in formatting.
3. Rule out values that cannot match: an email alias, a value with surrounding whitespace, or an attribute Veza does not compare, such as Employee ID.
4. Confirm both the application and the identity provider have completed an extraction since the identity values were set.
5. Review the warnings returned by the last OAA push. Identity values that resolved to nothing are reported there.
6. If the only value the two systems share is an attribute Veza does not compare automatically, configure an [identity mapping](/4yItIzMvkpAvMVFAamTf/integrations/configuration/custom-identity-mappings.md) with a **Property** or **Custom Property** matcher.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/configuration/automatic-identity-matching.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.