> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/solution-architecture/identity/correlation-key.md). # Identity correlation: choosing a matching key Choose the value that links a person's accounts across every directory, application and feed — why it is a trusted workforce identifier and never a username, what OpenIAM can actually match on, and wh ## What this is, and when you need it The **correlation key** is the value OpenIAM uses to decide that a record arriving from a feed, or an account discovered in a directory, belongs to a person it already knows. Everything else in the design rests on it: entitlements attach to a person, certifications attest to a person, a leaver event revokes a person's access, and a federation trust asserts a person to another organization. If the key is wrong, none of those act on the right person. This is the most consequential decision in Part 2 and one of the two or three most consequential in the whole design. Make it before the first feed is built. Changing it afterwards means re-matching every account in every managed system, and there is no product function that does that for you. ## The decision | Candidate key | Why it is chosen | Why it fails | | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **A trusted workforce identifier** — an employee number, or an enterprise identifier minted for the purpose | Immutable, carried by every source, meaningless outside the organization, unaffected by name changes and forest boundaries | Not held by every population — contractors and partners frequently have none, which is a gap to fill rather than a reason to reject it | | **A username or account name** | It is present, it looks unique, it is what people say out loud | Different in every forest, changed on marriage and on transfer, reused after a leaver, and absent for people with no account. **Never the right answer** | | **Email address** | Present on nearly every record, and unique today | Mutable by design, and reissued — a leaver's address handed to a joiner matches the leaver, silently | | **Name, or name plus date of birth** | Available when nothing else is | Not unique at any real scale, changes, and is transliterated differently by different systems | | **A composite** — source system plus that system's local identifier | Works when no single value spans the estate | Needs a custom matching rule and a governed crosswalk you now own; correct, but it is a build | The house position is the first row, and the reasoning is in the second: **usernames differ across forests**. An organization with five Active Directory forests has, for one person, up to five account names that were minted by five different conventions at five different times. No amount of transformation makes them a stable key, and the moment one of them is renamed, the link breaks silently. ## What OpenIAM can actually match on A synchronization or a reconciliation decides which existing object a source record is by comparing one named OpenIAM field against one named source column. Seven values are valid for that field, and the drop-down offers exactly those seven: | Value | Label | What it compares | Suitable as a correlation key? | | ----------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `EMPLOYEE_ID` | Employee ID | The user's employee identifier, case-insensitively | **Yes** — the usual right answer for a workforce feed | | `USERID` | User ID | OpenIAM's own internal user identifier | Yes, but only a source that already stores it can use it — typically a second feed from a system OpenIAM provisioned | | `ATTRIBUTE` | Custom Attribute | A named user attribute, against its value set | **Yes** — this is where a minted enterprise identifier lives when it is not the employee ID | | `MANAGED_SYS_PRINCIPAL` | Managed System Principal | The account name on the configuration's own managed system | For a directory inventory, yes. As the key linking a person across systems, no | | `PRINCIPAL` | Principal | The account name on the default managed system | No — this is a username | | `EMAIL` | Email | Any of the user's email addresses, case-insensitively | No — mutable and reissued | | `NAME` | Name | Meaningful for roles, groups, organizations and resources. **On a user feed it is not a name match at all** | No | Two of those rows carry a trap worth stating in a design review rather than discovering in a run. **`NAME` on a user feed silently becomes a username match.** OpenIAM does not compare names on a user synchronization. It logs a warning and falls back to matching on the principal on the default managed system, so a configuration saved with `NAME` behaves as `PRINCIPAL`. If your design says "we match on name", it does not match on name. **An ambiguous match does not fail.** When the match value resolves to more than one OpenIAM user, the run updates the first candidate it finds, in no defined order, and reports success. There is no count check, no error, no failed record and no report row. Next run it may pick the other one. Only an *empty* match value is rejected and reported. Where one field cannot identify a person safely — the composite case — a custom matching rule replaces the built-in comparison. Write it to handle zero, one and many candidates explicitly, and to **stop** on many, because the built-in behaviour does not. ## Uniqueness is your responsibility, and nothing in the product will check it The employee identifier is a single string field on the user, and it is indexed for lookup. **It is not unique.** There is no constraint, no validation on save, and no warning: OpenIAM will hold two users with the same employee identifier quite happily, and every feed that matches on it will then update whichever of them it happens to find first. That combination — a non-unique key and a silently first-wins match — is the mechanism behind the worst class of identity incident an IAM programme can produce: one person's HR data repeatedly imported onto another person's identity, with clean run reports throughout, and entitlements granted accordingly. So uniqueness has to be established outside the product and before the first production run: * Prove the value is unique **in the source**, across every source, including historical records. * Prove it is unique **in OpenIAM** before the first import, and keep proving it — a duplicate introduced by a manual creation or a second feed is not detected. * Prove it is **present on every record** of every population you intend to match. An empty value is at least reported, but a run that reports thousands of empty-key failures is a design problem, not an operational one. * Prove it is **immutable**. A key that changes when a person transfers between subsidiaries is not a key; it is an attribute. ## Where else the key is used Correlation is not only a synchronization concern, which is why choosing badly is expensive in more places than people expect. **Reconciliation** compares a managed system against OpenIAM using the same match field. An account it cannot correlate is an orphan — and an estate whose key is a username produces orphans on every rename. **Inbound federation** correlates differently again. When another organization's identity provider authenticates a user into OpenIAM, the incoming assertion is resolved against the principals of a nominated managed system, with a resolver script available where the standard mapping cannot produce the value. That is the mechanism that makes identity translation possible across estates, and it is why the identifiers do not have to match on both sides — but it still needs a stable value on this side to resolve to. **The Access Gateway and application SSO** carry whatever identity you inject or assert. An application told the user is `jsmith` has been told a username; an application told the user is enterprise identifier `E0041882` has been told something that survives a rename. **Governance and evidence.** A certification campaign attests that a named person holds an entitlement. Where correlation is unreliable, the campaign is attesting to the wrong person, and the evidence it produces is worth nothing. ## What breaks later if you choose wrong State these plainly in a design review; they are the argument for spending a month on the key before building anything. | Choice | What breaks, and when | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A username as the key | The first rename breaks the link. The account becomes an orphan, its entitlements detach from the person, and the leaver process misses it. In a multi-forest estate this happens continuously | | An email address as the key | A reissued address attaches a leaver's history to a joiner. Nothing reports it | | A key that is not unique | Two people's data merge onto one identity, repeatedly, with successful run reports | | A key that changes on transfer | The person appears to leave one organization and join another. Access is revoked and re-granted, history is broken, and the enterprise view shows two people | | A key that only employees have | Every non-employee is either matched on something weaker or not matched at all. The contractor population becomes the orphan population | | No key agreed with the other platform | Two governance platforms cannot maintain one view of a person, and a federation trust has nothing stable to translate | The last row is a Part 5 deadline on a Part 2 decision, and it is the one that surfaces latest. ## What we recommend **Use a trusted workforce identifier, held in the employee identifier field, and match on `EMPLOYEE_ID`.** It is the right answer for the large majority of workforce estates, it is the field the product is best behaved about, and it keeps the design legible to everyone who reads it. **Where no single trusted identifier spans the estate, mint one** rather than settling for a weaker value. That is the subject of [Choosing the enterprise unique identifier](/solution-architecture/identity/unique-identifier.md), and it is a smaller piece of work than the failure modes above. **Where a minted identifier is held as a user attribute rather than as the employee identifier, match on `ATTRIBUTE`** and name the attribute in the design. Do not overload the employee identifier field with two different kinds of value depending on population; a field that means different things for different people is not a key. **Never match a user feed on `PRINCIPAL`, `MANAGED_SYS_PRINCIPAL`, `EMAIL` or `NAME`.** `MANAGED_SYS_PRINCIPAL` remains the correct choice for a directory inventory whose purpose is to discover accounts on that one system — which is a different job from correlating a person. **Run the duplicate check before the first production import, and schedule it.** The check is cheap. The incident it prevents is not. The circumstance that changes this advice is an estate where OpenIAM provisioned the accounts in the first place and every source can carry OpenIAM's own user identifier. There, `USERID` is stronger than anything else on the list — but it is available only for feeds from systems OpenIAM already owns, which is rarely the joiner feed. ## What OpenIAM does not do here * **The employee identifier is not unique and is not validated.** No constraint, no save-time check, no warning. Uniqueness is entirely yours to establish and to maintain. * **An ambiguous match is not an error.** The first candidate found wins, silently, with a successful run report. There is no way to make the built-in matching fail on multiple candidates — that needs a custom matching rule. * **`NAME` is not a name match on a user feed.** It falls back to the principal on the default managed system, with one warning line per run as the only trace. * **There is no crosswalk table.** OpenIAM holds no product object mapping one system's identifier to another's. A composite or translated key lives in a custom matching rule and in attributes you populate and own. * **There is no re-correlation function.** Changing the correlation key after accounts are linked is not a supported operation with a button; it is a data exercise across every managed system, planned and executed by you. * **Nothing detects that a key has changed value for a person.** A source that starts issuing new identifiers presents as a population of joiners and a population of orphans, not as an error. ## Related * [Choosing the enterprise unique identifier](/solution-architecture/identity/unique-identifier.md) — what to do when no existing value is good enough. * [One person, many accounts](/solution-architecture/identity/one-person-many-accounts.md) — what the key is linking, once it is chosen. * *How a synchronization matches and processes a record* in the Administration Guide — the matching fields, the valid values and the two silent degradations, with the checks that confirm them. * *Resolve orphan accounts* in the Administration Guide — what correlation failure looks like operationally. *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/solution-architecture/identity/correlation-key.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.