Category: User Provisioning

Attribute Mapping

Also known as: Attribute Mappings, Attribute Transformation

Simply put

Attribute mapping is the process of matching pieces of identity data from one system to the corresponding fields in another system, so information about a user lines up correctly on both sides. For example, a source directory's user data can be mapped to the fields an application expects when a user account is created or updated. This keeps user details consistent as they move between connected systems.

Formal definition

Attribute mapping defines how identity attributes from a source (such as an on-premises directory or identity provider) are assigned, translated, or transformed into the target attributes consumed by a downstream application or directory. It is typically configured within a provisioning or synchronization flow to control which attributes are exchanged and in which direction; for example, Okta supports mappings such as App-to-Okta and Okta-to-App, and Microsoft Entra allows per-object-type (user or group) mappings, including custom and transformed attributes. Attribute mapping is primarily an identity lifecycle and provisioning concern (often paired with SCIM-based provisioning) and is distinct from runtime access enforcement; the exact transformation capabilities, directionality, and supported expressions depend on the vendor and connector configuration.

Why it matters

Attribute mapping is foundational to keeping identity data consistent across the connected systems that make up a modern identity fabric. When a source directory or identity provider provisions a user into a downstream application, the two systems rarely name or format their fields identically. Mapping resolves this mismatch so that a user's details line up correctly on both sides, which in turn supports accurate account creation, updates, and deprovisioning throughout the identity lifecycle.

Errors in attribute mapping tend to surface as subtle but consequential problems. A misdirected or malformed mapping can populate the wrong field, drop a required attribute, or overwrite good data during synchronization, leading to broken accounts, failed provisioning, or stale records that persist longer than they should. Because attributes such as email, username, or group membership are frequently consumed by downstream applications to drive account matching and profile data, incorrect mappings can cascade into operational and data-quality issues across many systems at once.

It is important to keep attribute mapping in its proper scope. It is primarily an identity lifecycle and provisioning concern, governing which attributes are exchanged and in what direction, and is distinct from runtime access enforcement. An attribute that arrives via a mapping may later feed an authorization decision, but the mapping itself does not evaluate policy or grant access; conflating the two can lead teams to place enforcement logic where only data transformation belongs.

Who it's relevant to

IAM Engineers

Engineers who configure provisioning connectors rely on attribute mapping to control which attributes flow between source and target and in which direction. They must understand vendor-specific behavior, such as Okta's App-to-Okta and Okta-to-App mappings or Entra's per-object-type mappings, to avoid misdirected data, dropped fields, or unintended overwrites during synchronization.

Identity Governance Leads

Because attribute mapping is an identity lifecycle and provisioning concern, governance leads depend on accurate mappings to keep user records consistent as accounts are created, updated, and deprovisioned across connected systems. Reliable mappings support the data quality that downstream lifecycle processes assume.

System Administrators

Administrators managing directory synchronization and application provisioning, including SCIM-based flows and hybrid scenarios such as Entra cloud sync between on-premises and cloud objects, use attribute mapping to ensure that user and group attributes land in the correct target fields, and they troubleshoot mapping errors when profile data fails to line up.

Inside Attribute Mapping

Source Attribute

The attribute as it exists in the authoritative or upstream system, such as an LDAP directory attribute, a SAML assertion attribute, or an OIDC claim. Attribute mapping begins by identifying this source field before transformation or projection into a target.

Target Attribute

The attribute as expected by the consuming system, such as a SCIM user resource field, a service provider's expected assertion attribute, or an application profile field. The mapping defines how source values populate this target.

Transformation Logic

Optional rules that convert, normalize, concatenate, or reformat a source value before it is written to the target, for example combining given name and surname into a display name, or normalizing case and formatting. Availability and expressiveness of transformations vary by vendor and configuration.

Claim and Assertion Mapping

In federation contexts, the correspondence between values in a SAML 2.0 assertion or an OIDC ID token claim and the attributes an application consumes. This determines which identity attributes are conveyed at authentication time versus which are provisioned separately.

Provisioning Mapping

In IGA and SCIM-based flows, the mapping that governs how attributes are written during account creation, update, and deprovisioning. This is a lifecycle concern distinct from the runtime attributes presented in a token or assertion.

Identifier Correlation

The mapping of an attribute used to correlate or match an identity between systems, such as linking a source unique identifier to a target account. Choosing a stable, non-reassignable correlation attribute is typically critical to avoid mismatched accounts.

Common questions

Answers to the questions practitioners most commonly ask about Attribute Mapping.

Is attribute mapping the same as attribute transformation?

Not exactly. Attribute mapping refers to defining the correspondence between a source attribute and a target attribute (for example, mapping a directory's mail attribute to a SAML assertion's email claim). Transformation, modifying, formatting, concatenating, or deriving values, may occur as part of a mapping configuration in many products, but the two are conceptually distinct. A mapping can be a direct one-to-one pass-through with no transformation at all. Whether transformation logic is available and how expressive it is depends on the specific IdP, provisioning engine, or federation product.

Does attribute mapping determine what a user is allowed to do?

No, not by itself. Attribute mapping governs how identity attributes are named, shaped, and delivered between systems; it does not make authorization decisions. Mapped attributes may later be consumed as inputs by an authorization mechanism, such as an ABAC or PBAC policy decision point that evaluates those attributes, but the mapping step only makes the data available in the expected form. The access decision is a separate concern performed by the enforcement or policy layer that reads those attributes.

How do I handle a source attribute that is missing or null during mapping?

Behavior depends on the product and configuration. In most deployments you can specify whether a missing source attribute results in the target attribute being omitted, set to a default value, or treated as an error that halts provisioning or assertion issuance. It is generally advisable to decide explicitly per attribute, since a downstream system may reject an assertion or SCIM request that lacks a required attribute, or may misbehave if it receives an empty value where it expected none. Confirm the specific null-handling semantics of your IdP or provisioning connector rather than assuming a default.

Where should attribute mapping be configured when the same attributes flow through both SCIM provisioning and SSO assertions?

These are typically two separate mapping configurations because they serve different purposes: SCIM provisioning maps attributes into the target system's account lifecycle (create, update, deprovision), while SSO mapping shapes claims delivered in a SAML assertion or OIDC token at authentication time. Depending on the platform, they may draw from the same source attributes but are usually configured independently and can drift apart. Keeping them consistent, so a provisioned attribute matches what the assertion later carries, generally requires deliberate coordination rather than a single shared mapping.

How do I map a multi-valued source attribute, such as group memberships, to a target?

This varies by protocol and product. Some targets accept multi-valued attributes or arrays directly, while others expect a single value or a delimited string, which may require transformation or filtering during mapping. In federation, whether an assertion or token can carry a repeated attribute or claim depends on the standard profile and the relying party's expectations; some consumers only read the first value. Verify how both the source format and the target's expected format handle multiple values before relying on the mapping to preserve all of them.

How can I test and validate attribute mappings before rolling them out?

Common approaches include using a test or non-production user account, inspecting the actual assertion or token issued (for example, decoding a JWT to confirm claim names and values, keeping in mind a signed token is still readable unless it is also encrypted), and reviewing provisioning logs to confirm the target account received the expected attribute values. Many IdPs and provisioning tools provide a preview or simulation feature for this purpose. Validating against the target system's actual requirements, rather than assuming the mapping is correct because it saved without error, helps catch naming, format, and cardinality mismatches early.

Common misconceptions

Attribute mapping in a federation assertion is the same as provisioning attributes into the target system.

Attributes conveyed in a SAML 2.0 assertion or an OIDC ID token at authentication time are a runtime concern, whereas provisioning attributes through SCIM or a directory write is a lifecycle (IGA) concern. A given attribute may be mapped in one flow, the other, or both, and they are configured and governed independently.

Mapping an attribute into a token or assertion also determines what the user is allowed to do.

Attribute mapping populates identity or context attributes; it does not by itself make an authorization decision. In attribute-based (ABAC) or policy-based (PBAC) models a policy decision point still evaluates those attributes against policy. Mapping supplies inputs to authorization but is separate from enforcement.

Once a mapping is defined, source and target attributes will always contain equivalent, interchangeable values.

Depending on configuration, formats, encodings, and semantics can differ between systems, which is why transformation logic and identifier correlation exist. Without normalization and a stable correlation attribute, mappings can produce mismatched or inconsistent values across systems.

Best practices

Choose a stable, unique, non-reassignable attribute for identity correlation between systems to reduce the risk of mismatched or orphaned accounts.

Keep runtime assertion and token claim mappings separate from provisioning mappings, and document which attributes each flow is responsible for.

Normalize formats, case, and encodings through explicit transformation logic rather than assuming source and target values are interchangeable.

Map only the attributes actually required by the target system to limit unnecessary disclosure of identity data in assertions, tokens, or provisioned profiles.

Validate mappings against the specific standard profile in use (for example SAML 2.0 assertion attributes, OIDC Core claims, or SCIM user schema fields), since expected attribute names and structures vary.

Test mappings for edge cases such as missing source values, multi-valued attributes, and updates during the lifecycle, and confirm behavior aligns with the target system's requirements before production rollout.