Different systems store the same fact under different names, in different shapes. Mapping is the translation layer that lets them understand each other.

The problem in one sentence

One person is described in many places, and each place describes them a little differently. Okta calls the person’s email “email”. A directory may call it “mail”. An app may call it “emailAddress” or “work_email”. A payroll system may call the department “dept” and store it as a number. If Okta simply copied everything unchanged, most apps would reject it or ignore it.

What a mapping does

A mapping is a rule that says: take this fact from this place, optionally change it in a certain way, and put it into that box in the other place. A set of such rules, one per fact, is called an attribute mapping, and the facts themselves are called attributes.

Where it matters in daily life

• New accounts. When Okta creates an account in an app, mappings decide what goes into each field.
• Changes. When a person’s title or manager changes, mappings decide which apps hear about it and in what form.
• Sign-in. When a person signs in to an app, mappings decide which facts are placed in the sign-in message the app receives.
• Imports. When Okta reads people from a directory or an app, mappings decide how those facts become the Okta profile.
• Access decisions. Many rules for groups and policies rely on attributes, so a wrong value can quietly grant or block access.

Before translating facts, you need to know what a fact looks like inside Okta. Three simple words cover it: attribute, profile and schema.

Attribute

An attribute is one named fact about a person, such as first name, email, job title or employee number. Each attribute has a name, a type (text, number, true or false, or a list) and rules about whether it is required, and whether it must be unique.

Profile

A profile is the full set of attribute values for one person in one system. The Okta profile for Priya holds her first name, last name, email, department and so on. The profile in a different app may hold only some of those facts, and some extra ones.

Schema

A schema is the blueprint of a profile: the list of all attributes that exist, with their types and rules. The profile holds the facts, and the schema describes what facts are allowed. Adding a new kind of fact means changing the schema first.

Base and custom attributes

Okta’s user profile comes with a standard set of attributes called base attributes, such as first name, last name, email, login, title, department, manager, city and phone numbers. These are built in, and some of them cannot be removed. You can add your own, called custom attributes, for facts the standard set does not cover, such as badge number, cost center or contract end date.

Types and rules

Each attribute has a data type. Text is the most common. Others include number, true or false, and list of values. Types matter in mapping, because an app that expects a number will refuse the word “twelve”, and an app that expects a list will refuse one long sentence. Attributes also have rules, such as maximum length, allowed values, whether a value is required, and whether the value must be unique across all people.

Okta keeps several profiles side by side. The tool you use to see them and connect them is called the Profile Editor.

Where mappings live

In the Admin Console, the Profile Editor lists the profiles Okta knows about and lets you work with their attributes and their mappings. It is the home of attribute mapping. Menu names can differ slightly between versions, so look for Profile Editor under the Directory area.

The main kinds of profile

Okta in the middle

The Okta user profile sits in the middle like a hub. Facts flow into it from sources such as HR, directories and other identity providers. Facts flow out of it to apps. Each arrow in this picture is a mapping. Keeping Okta in the middle means there is only one place that has to understand every system’s format: the mappings around the hub.

Every mapping has a direction. Mixing up directions is the most common beginner mistake.

The two directions

For an app, there are two mapping screens, and they are separate. The Okta to App mapping controls what Okta sends into the app when it creates or updates an account. The App to Okta mapping controls what Okta takes from the app when it imports, and how that is written into the Okta profile.

flowchart LR
    SRC["Master source: HR or directory"] -->|"Source to Okta mapping"| OK["Okta user profile"]
    OK -->|"Okta to App mapping"| AP["App user profile"]
    AP -->|"App to Okta mapping"| OK
    OK -->|"Attribute statement or claims"| SO["Sign-in message to the app"]
    

Reading the picture

On the left is the official source of facts. A mapping carries those facts into the Okta profile. From Okta, an outgoing mapping carries chosen facts to each app’s profile when accounts are created or updated. An incoming mapping from the app can bring facts back, if the app owns some of them. A fourth path, at the bottom, is not about accounts at all. It is about sign-in: when a person logs in, selected facts are placed into the sign-in message the app receives.

Who is the master?

For each attribute, one system should be the master, meaning its value is the one to trust. If HR is the master of job title, then the title flows from HR to Okta and onward to the apps, and nobody should edit it in the middle. If the app is the master of a fact, such as a locally chosen display name, then the flow goes the other way. Two masters for one attribute cause a tug of war in which each side keeps overwriting the other.

A small set of words appears in every mapping conversation. Learn these once and the Admin Console becomes much easier to read.

About the data

About the rule

About where mappings are used

A mapping is not a free-floating idea. It sits inside a small machine made of profiles, a mapping engine, and the places that use the result.

flowchart TD
    A["Fact changes at a source"] --> B["Source profile updated"]
    B --> C["Source to Okta mapping applied"]
    C --> D["Okta user profile updated"]
    D --> E{"Which uses need this fact?"}
    E -->|"Account sync"| F["Okta to App mapping applied"]
    E -->|"Sign-in"| G["Attribute statement or claim built"]
    E -->|"Access rules"| H["Group rules re-evaluated"]
    F --> I["App account updated"]
    G --> J["Next sign-in carries the new value"]
    H --> K["Group membership may change"]
    

Reading the picture

A fact changes first at its source, for example a manager is changed in the HR system. The source mapping carries the change into the Okta profile. From there, the same change may affect three different things. Apps that store the fact receive an update through the outgoing mapping. Apps that receive the fact at sign-in will see the new value the next time the person logs in. Group rules that use the fact are checked again, and group memberships may change, which in turn may change app access.

The mapping engine

The part of Okta that does this work can be called the mapping engine. For each rule, it reads the source value, applies the expression if there is one, checks the result against the target attribute’s type and rules, and writes it. If the result is invalid, for example too long or the wrong type, the write fails and an error is recorded. The rest of the profile is usually still processed, so one bad attribute does not always stop everything, but it may stop the whole create or update for the app, depending on the app.

Some facts can be copied as they are. Others must be shaped first. Okta offers both options.

Direct mapping

A direct mapping simply copies the value. If the Okta first name is “Priya”, the app first name becomes “Priya”. Most mappings are direct, because most apps ask for the same simple facts that Okta already holds. Direct mappings are easy to read, easy to test and rarely cause surprises, so prefer them whenever they are enough.

Expression mapping

An expression is a small formula written in Okta’s Expression Language. It is used when the target needs something that the source does not hold directly. Common reasons are joining two facts, cutting a piece out of one, changing letter case, choosing between values, or building a value that follows a naming rule.

Where expressions are allowed

Expressions can be used in several places: in profile mappings, in group rules, in SAML attribute statements, in OpenID Connect claims and in some policy conditions. The language is the same in all of them, which is a benefit, because a skill learned once can be reused. The available inputs differ slightly from place to place, so test each one where you use it.

Keep expressions simple

An expression is code, and code needs care. A long expression that nests many conditions is hard to read, hard to test and easy to break when somebody changes a profile field it relies on. A good rule is that if an expression needs a paragraph to explain, it probably belongs earlier in the pipeline, for example in the HR system or in a prepared custom attribute.

Common things people do with expressions

• Join facts. Combine first and last name into a display name, or build an email address from a username and a company domain.
• Cut facts. Take the first letter of a name, the part of an email before the at sign, or the last four characters of a number.
• Change case. Turn text into all lower case or all upper case so that comparisons work.
• Choose between facts. Use one value when it exists and another when it is empty, so the target never receives a blank.
• Test a condition. Send one value when a condition is true and another when it is false, such as a manager role for higher levels.
• Look inside groups. Check whether a person belongs to a group and send a matching flag or role.

Each of these is small by itself. Trouble starts when several are stacked into one long formula. A good habit is to give every expression a short written purpose in your notes, such as “builds display name as first plus last, falls back to login”. When the purpose is clear, the next administrator can judge whether the formula still serves it.

The same idea appears in several different features. Each has its own screen and its own timing, so it helps to know them side by side.

Provisioning mappings versus sign-in mappings

This distinction confuses many beginners. A provisioning mapping writes values into the app’s stored account, and they stay there until the next update. A sign-in mapping sends values in the login message every time, and the app usually reads them fresh at each login. Some apps use only one of the two. Others use both, and a mismatch between them is a classic source of “the right value is in one place and the wrong value in another”.

Import mappings

When Okta reads a person from a directory or app, the import mapping decides how each incoming fact is written into the Okta profile. A common design is to let a directory such as Active Directory be the master for name and department, so import mappings carry those facts in and the Okta profile follows the directory. In such a design, editing those fields directly in Okta is pointless, since the next import will overwrite them.

Identity provider mappings

When people sign in through another identity provider, such as a partner company, Okta can create or update their profile at login. The identity provider mapping decides what is taken from the incoming sign-in message and written into the Okta profile. This is the mapping side of just-in-time creation, and it needs the same care as any import.

A mapping can be perfect in meaning and still fail because the value is the wrong shape. Types and formats are where many failures hide.

Common mismatches

Required and unique rules

If the target attribute is required and the source has no value, the create will fail. If the target must be unique and two people produce the same value, the second one will fail. A classic case is building a username from the first letter of the first name and the last name. Two people named “P Sharma” collide. A design that never considers collisions works on day one and fails on the day the second person with the same name arrives.

Defending against bad data

• Validate early. Fix bad values at the master source so they never travel.
• Normalize. Make the case and spacing consistent in one place, then trust it downstream.
• Provide defaults. Where an app requires a value, supply a harmless default when the source is empty.
• Plan for collisions. Add a number or another fact to usernames, and decide who resolves conflicts.
• Test with ugly data. Try empty values, very long values, accents and apostrophes.

A short story of one bad value

Consider a person named Anne-Marie O’Neil. Her last name has an apostrophe and her first name has a hyphen. An app builds usernames by joining the first letter of the first name to the last name, then removing anything that is not a letter. The result is “aoneil”, which is fine. But an older mapping in a second app does not remove the apostrophe, and that app refuses names with punctuation. Her account is created in the first app and fails in the second. Nobody notices for a week, until she asks why she cannot open a tool. The lesson is that the same person can succeed in one mapping and fail in another, so test each target separately.

It is also worth testing names that are very short, such as two letters, and names that are very long, such as a double-barreled surname with several parts. Real populations contain all of these, and a mapping that was only tried on simple names such as “John Smith” will meet surprises in production.

A mapping has a second setting that is easy to miss: when it is allowed to run. This single choice decides whether a value is a one-time start or a living link.

The two timing choices

For app provisioning mappings, each attribute can be set to apply when the account is created and updated, or when it is created only. With create and update, every change in Okta is pushed to the app. With create only, the value is sent once at the start and then left alone, even if the Okta value changes later.

Choosing for each field

Ask a simple question for each field: after the account exists, who should be allowed to change this value? If the answer is “only Okta or HR”, use create and update. If the answer is “the app owner or the person, inside the app”, use create only. Usernames are a special case. A username is usually the key that links the app account to the Okta user, so changing it later can break the link. Most teams set username to create only for that reason.

When more than one system can feed the same Okta attribute, Okta needs a rule for who wins. That rule is called profile source priority.

The problem of many feeds

A company often has more than one system that knows about its people. HR knows the title. The directory knows the email. An app knows a phone number. All of them may want to write to the Okta profile. If two of them write the same attribute with different values, the final value depends on timing, and it can flip from one to the other without anyone noticing.

Ways Okta helps

• Profile source. You can designate one source as the master for the whole profile, such as a directory or an HR integration. Okta then treats that source as authoritative.
• Attribute-level sourcing. For individual attributes, you can say which source is allowed to write them, and in a priority order if more than one is allowed.
• Read-only attributes. Attributes fed by a master can be locked so that administrators cannot edit them by hand in Okta.
• Clear import mappings. Only mapping a field from the source that owns it makes the right behavior the default.

The exact options depend on your Okta features and edition, so check the current documentation for the controls available to you.

flowchart TD
    HR["HR system: owns title, department, manager"] --> OK["Okta user profile"]
    DIR["Directory: owns email and login"] --> OK
    APP["Application: owns last login time only"] --> OK
    OK --> A1["App one gets title and department"]
    OK --> A2["App two gets email and manager"]
    

Reading the picture

The diagram shows a clean design. Every arrow into Okta carries only the attributes that source owns. HR does not write email. The directory does not write title. The application writes only one narrow fact. Because no attribute has two sources, there is nothing to fight over. The two apps on the right receive from Okta only, so they always see consistent data.

How to think about priority in practice

Priority is easiest to understand with a simple rule: the closest source to the truth wins. HR is closer to the truth about a job title than a directory is, because the directory usually copies it from HR or from someone’s manual entry. A directory is closer to the truth about a login name, because it is where the login is created. Write this down for each attribute, share it with the teams that own the systems, and ask them to confirm it. A short meeting that settles ownership prevents months of silent disagreement later.

When you cannot agree on a single master, choose the second best option: allow only one system to write the attribute at any time, and mark the other as read-only. A value that is always correct in one place, and is copied faithfully everywhere else, is far better than one that is sometimes right in several places.

The standard attributes do not cover everything. Adding your own is easy. Adding the right ones, and in the right way, takes thought.

Why add a custom attribute

Typical reasons are to hold a cost center, a contract end date, a badge number, a region code, an access level, a business unit or a flag that says the person is a contractor. If a group rule, a policy or an app needs a fact that Okta does not hold, a custom attribute carries it.

Designing a good attribute

Do not create too many

Each attribute has a cost: documentation, mapping, testing and risk of misuse. A profile with a hundred barely used attributes becomes confusing and slow to manage. Add an attribute only when a real use needs it, and remove those that nothing uses. Before adding, check whether an existing standard attribute, such as cost center or organization, already fits.

Attributes that carry decisions

Some custom attributes are not facts but decisions, such as “app access level”. These are dangerous when people can edit them, because the attribute becomes a way to grant access. If an attribute drives access, make it read-only for users, feed it only from a trusted source, and watch changes to it in the logs.

Groups are where attribute values turn into access. The link between the two is one of the most powerful and most misused parts of Okta.

Group rules

A group rule places people in a group automatically, based on their attributes. For example, a rule can say: if the department is Sales, add the person to the Sales group. When a person’s department changes, the rule runs again, removing them from the old group and adding them to the new one. If the Sales group is assigned to apps, the change in an attribute becomes a change in access with no one clicking anything.

Pushing groups to apps

Some apps have their own groups. Okta can push a group, with its members, into the app. This is a different kind of mapping, as it maps group names and members, not user attributes. The app group name usually follows the Okta group name unless you set it otherwise.

Groups in sign-in messages

Apps often need to know a person’s groups at sign-in so they can decide what the person may do. Okta can include groups in a SAML attribute statement or in an OpenID Connect claim. A filter decides which groups are sent, for example only those whose names start with a chosen prefix. Without a filter, an app may receive far more groups than it needs, which can leak information about the organization and enlarge the sign-in message.

Two attributes that look the same but are not

Beginners often confuse the login of a person with their email. The login is the name the person types to sign in to Okta. The email is where messages are sent. They often have the same value, but they do not have to. Some companies keep them different on purpose, for example a login based on an employee number and an email based on a name. Apps may want one, the other or both, so check which one each app expects and map it accordingly.

In the same way, the display name, the full name built from first and last name, and the nickname are different facts. If an app shows the wrong one in its user list, the cause is usually a mapping that points to the wrong source attribute, not a data error.

At sign-in, the app wants to know a few facts about the person. Okta supplies them in the sign-in message through a mapping of its own kind.

SAML attribute statements

In a SAML sign-in, Okta sends a signed message called an assertion. Inside it is a list of attribute statements, each with a name and a value. The administrator chooses the names the app expects and the Okta source for each value, either a profile attribute or an expression. Some apps require exact names, so a typo or a different capital letter can leave the app without the fact it needs.

OIDC claims

In an OpenID Connect sign-in, the same idea appears as claims placed in tokens. Some claims come from a requested scope, such as email or profile. Custom claims are added through the authorization server, with a name, a value expression, and conditions saying which tokens and scopes include them.

sequenceDiagram
    participant P as Person
    participant A as Application
    participant O as Okta
    P->>A: Opens the app
    A->>O: Please sign this person in
    O->>P: Asks for credentials and checks policy
    P->>O: Proves identity
    O->>O: Reads the user profile
    O->>O: Applies the attribute statement or claim mapping
    O->>A: Signed message with name, email, groups and roles
    A->>A: Reads the facts and decides what the person may do
    A->>P: Shows the app
    

Reading the picture

The mapping step happens inside Okta after the person proves who they are. Okta reads the current profile, builds each attribute or claim from its mapping, signs the message and hands it to the app. Because it happens at every login, the app receives current values. This is why a corrected title shows up at the next login even if the account stored in the app still holds the old one.

Choosing what to send

• Send only what the app needs. Extra facts leak information and make messages larger.
• Match the app’s expected names. Copy them from the app’s documentation without changes.
• Pick a stable identifier. The main name identifier should never change for a person, or the app will treat them as a new user.
• Be careful with sensitive facts. Do not send personal data to an app that has no need for it.
• Test with a real login. Sign in and inspect what the app received, using the app’s own diagnostic view or a trace tool.

Here is a safe route for adding or changing a mapping. The names of screens may differ slightly, but the order of thinking stays the same.

What to compare after a push

After any bulk push, compare three things for a sample of people: the value in the source, the value in the Okta profile, and the value in the app. All three should agree for fields that follow Okta. Differences point to a specific stage: a gap between source and Okta means the import or feed is at fault, and a gap between Okta and the app means the outgoing mapping or the app itself is at fault. Keep a small spreadsheet of sample checks, with dates, so you can show what was verified and when.

Also keep a way back. Before changing an important mapping, note the old rule exactly, including the timing setting. If the new rule causes trouble, you can restore the old one quickly. Pushing a corrected value again is then a second, calmer step, not an emergency rebuild.

Saving a new mapping does not always change the data already in the app. Knowing when old data is refreshed prevents surprises.

What happens after you save

A new mapping usually applies from the next create or update. People who already have accounts keep their old values until something triggers an update for them. If you want existing accounts to pick up the new mapping straight away, you can use an action to push the mapped values again, often called reapply mappings or a forced sync. The name and place in the console depend on the app and version.

Why wait, and why not

• Pushing for everyone at once can be heavy. A bulk push for thousands of people can hit the app’s rate limits and slow other work.
• A wrong mapping spreads fast. If you reapply before testing, you spread a mistake to everyone.
• Letting it flow over time is gentler. Updates reach people as their profiles change, with no spike.
• But old values may be wrong now. If the old mapping caused harm, such as wrong roles, waiting leaves the harm in place.

A cautious pattern

Many mapping problems are not about logic but about consistency. Small habits in names and formats prevent large headaches.

Names of attributes

Choose one style for variable names and use it everywhere. Short, lower-case first words followed by capitalized words are common. Avoid spaces and special characters. Avoid names that look like standard ones, such as another “department” with a slightly different spelling, because they cause people to map the wrong one.

Formats of values

Where to normalize

Normalize as close to the master as possible. If HR writes “sales”, “Sales” and “SALES  ” in the department field, a group rule that looks for “Sales” will miss two of them. Fixing it in the HR system fixes it for every downstream user. If you cannot change the source, normalize once in the import mapping, and then every other mapping and rule can rely on the clean value.

Attribute mapping lives in time. When a value arrives, when it is read and what happens if it is missing all change the result.

Empty values

A missing value can mean three different things: the person has no such fact, the fact has not arrived yet, or something broke in transit. A mapping should handle empty values on purpose. Options are to send nothing, to send a default, or to stop the action and raise an error. For a required target field, a default or a stop is necessary. For an optional field, sending nothing is usually best, but be aware that some apps treat “nothing sent” as “leave unchanged”, and others treat it as “clear the value”.

Order of events

In a new joiner flow, the account may be created before all the facts are ready. For instance, the manager may be filled in a day after the account is created. If the app needs the manager at creation, the create will fail or be incomplete. If it accepts a later update, the second update fills it in. Design your joiner process so that required facts arrive first, or so the mapping provides a default that later updates replace.

sequenceDiagram
    participant H as HR System
    participant O as Okta
    participant A as Application
    H->>O: New hire record with name and department
    O->>O: Apply source mapping
    O->>A: Create account with mapped values
    A-->>O: Account created
    H->>O: Manager assigned a day later
    O->>O: Apply source mapping
    O->>A: Update account with manager
    A-->>O: Update accepted
    

Reading the picture

The first message creates the account with the facts known at hiring. A day later, HR assigns the manager. The same mapping machinery detects the changed fact and sends an update. The key design point is that the mapping for manager must be set to apply on update, not create only. If it were create only, the manager would never reach the app.

Delays and eventual consistency

Changes travel through steps: the source, Okta, the app. Each step takes time, and some run on schedules, such as directory syncs or HR imports. So after a change in the master source, the target may stay out of date for minutes or hours. A system that is allowed to be briefly out of step but ends up correct is called eventually consistent. Plan for it: do not test immediately and declare failure, and tell users how long a change normally takes.

Privacy and minimum data

Some attributes are personal: home address, personal phone, birth date, national identifier. Mapping them to an app that does not need them creates risk with no benefit. If the app is breached, that data is exposed. If laws on personal data apply to your organization, sending extra data may also create legal duties. Ask of every mapped attribute: what does this app do with it, and what would happen if it were missing? If the answer to the second question is “nothing”, remove the mapping.

Remember also that sign-in messages travel through the person’s browser. They are signed, and they can be encrypted for apps that support it, but their contents may still be visible in logs or developer tools on the person’s own device. Avoid placing highly sensitive facts in them unless the app truly requires it and the message is protected.

Attributes are not only data. They are often the reason a person is allowed in or kept out. Mapping errors can therefore become security problems.

Why attributes are security-relevant

Many decisions depend on attributes. A group rule reads the department to decide who joins the Finance group. An app reads a role claim to decide who is an administrator. A policy reads a flag to decide who may sign in without a second step. If the attribute is wrong, the decision is wrong. If someone can change the attribute, they can change the decision.

The main risks

Protections

• Keep access-driving attributes read-only for users. Allow edits only through the master source or by a small set of administrators.
• Use stable, non-reusable identifiers. Prefer a permanent internal ID over an email or a name for the main identifier.
• Send the minimum. Limit attribute statements, claims and group filters to what each app needs.
• Limit who can edit mappings. Mapping administration is a powerful role. Give it to few people, with strong sign-in.
• Restrict inbound writes. Let external providers write only the attributes you can safely trust, and nothing that decides access.
• Review changes. Treat a mapping change like a code change: a second person reviews it, and the reason is recorded.
• Log and alert. Watch the logs for changes to mappings, schemas and sensitive attributes.

Questions that speed up a support call

• Is it one person or many? One person suggests bad data for that person. Many suggest a shared mapping or feed problem.
• Did it ever work? If yes, ask what changed: a mapping edit, a schema change, a new feed or an app update.
• Is it at creation or at change? Creation problems point to required fields and collisions. Change problems point to timing and update settings.
• Is it provisioned or at sign-in? The two paths use different mappings and different tools to inspect.
• Is the value empty or wrong? Empty values suggest an unmapped or blank source. Wrong values suggest a bad expression or a second writer.

Asking these five questions first often reduces a long investigation to a single targeted check. They are worth putting on a card next to the help desk.

When a value is wrong, you need a calm method to find where it went wrong. The path from source to target has only a few steps, so the search is short if you do it in order.

Where to look

A calm way to find the cause

Common problems and usual causes

Central, rule-based mapping is very useful. It also brings costs and design choices that deserve open discussion.

Design decisions to make on purpose

Review rhythm

Mappings age. People leave the team that wrote them, apps change their field names, and the company reorganizes. A light review twice a year keeps them healthy. Walk through each app: are the mapped fields still used, is each master still correct, are expressions still needed, and are access-driving attributes still protected? Remove what is unused. A smaller set of mappings is easier to trust.

Teams that manage mappings well repeat a handful of habits. Teams that struggle repeat a handful of mistakes.

Good patterns

Anti-patterns to avoid

A short checklist

• Does every mapped attribute have a named master?
• Is each mapping direction clearly understood and documented?
• Is the apply timing chosen on purpose for each field?
• Are access-driving attributes protected from self-editing?
• Has each mapping been previewed for several people, including empty cases?
• Does the sign-in message send only what the app needs?
• Is there an owner and a review date for each mapping set?

Mapping is cheap for one person and heavy for fifty thousand. Planning for scale keeps changes safe and quick.

Where the load comes from

A single mapping change can touch every person who has an account in an app. If a company has thirty thousand people and ten apps, a mapping change that is reapplied to everyone can create hundreds of thousands of update requests. Large imports from a directory or an HR system also carry thousands of records at once. These are bursts of work, and the apps at the receiving end usually limit how fast they will accept requests.

Practical habits for scale

• Reapply in waves. Push in groups, with checks between waves.
• Change at quiet hours. Run large pushes outside busy working times.
• Map only what is needed. Fewer attributes mean smaller messages and fewer failure points.
• Avoid frequent noisy attributes. A value that changes every minute, such as last activity time, should not trigger updates everywhere.
• Know each app’s limits. Note rate limits and plan large changes around them.
• Keep expressions light. Simple expressions run fast and are easy to reason about.

flowchart LR
    CH["Mapping change saved"] --> PL["Plan waves: pilot, team, department, company"]
    PL --> W1["Wave 1: pilot group"]
    W1 --> C1{"Errors or wrong values?"}
    C1 -->|"Yes"| FX["Stop, fix the mapping, retest"]
    FX --> W1
    C1 -->|"No"| W2["Wave 2: larger group"]
    W2 --> C2{"Errors or wrong values?"}
    C2 -->|"Yes"| FX
    C2 -->|"No"| W3["Wave 3: everyone"]
    W3 --> DONE["Sample check and record the result"]
    

Reading the picture

The plan splits the change into waves, from a small pilot group to the whole company. After each wave comes a check for errors or wrong values. If the check finds a problem, the process stops, the mapping is fixed and the wave is tried again. Only after a clean result does the next, larger wave begin. The loop is the safety feature. It makes sure a mistake is found on ten people, not on ten thousand.

Reliability

If an app is temporarily down, provisioning updates are retried, so values arrive once the app is back. If an import from a directory fails, the Okta profile keeps its last good values, but they may become out of date. After any outage, compare a sample of people between the source, Okta and the app to confirm that everything has caught up.

To make everything concrete, follow a fictional company, Northwind Retail, as it fixes a messy department attribute.

What the example teaches

The problem showed up in access, but its cause was a small data habit: a free-text field with two feeds. The cure was not a clever expression. It was a clear master, a clean source, a locked attribute and a staged rollout. Notice also that no step involved guessing. At each stage, the team compared the value at one place with the value at the next, and followed the chain until they found where it first went wrong.

Notice, too, what was not done. The team did not add an expression that tried to guess the right department from three spellings. That would have hidden the problem and left a fragile formula behind. Fixing data at its source is almost always cheaper than shaping it downstream.

Different organizations use attribute mapping in different ways. These short pictures show common situations.

Short answers to the questions beginners ask most.

Attribute mapping is the translation layer that lets Okta, apps, directories and identity providers share facts about people correctly.

Okta keeps a central user profile as a hub. Mappings carry facts into that hub from sources such as HR and directories, and out of it to apps, both when accounts are provisioned and when people sign in. A mapping can be a direct copy or a small expression, and it can apply on create only or on create and update. Good results depend on one master per fact, clean source data, stable identifiers, read-only protection for access-driving attributes, sending only what each app needs, and testing with awkward data before rollout. When something looks wrong, trace the value from the source forward, and the first place it is wrong is where the problem began.