Universal Directory in Okta
The single, cloud-based home for every person and their details. Learn what Universal Directory stores, how it connects to your other systems, how it keeps data accurate, and how to run it safely.
Every organisation keeps a list of its people. HR has one list. The email system has another. The sales tool, the code repository, the badge system, and the office laptop fleet each keep their own. Over the years these lists drift apart. A person changes teams in one list but not in the others. A leaver is removed from three lists but forgotten in a fourth. Nobody can say with confidence which list is right.
Okta’s answer to this mess is called Universal Directory. It is a central place inside Okta where every person’s profile lives, where details are cleaned and shared out to all connected apps, and where trusted sources such as HR systems can keep the information fresh. This guide explains Universal Directory from zero, one idea at a time, with plain examples.
1What Is Universal Directory?
Universal Directory is the place in Okta where user profiles, groups, and their attributes are stored and managed.
A directory is simply an organised list of people and things, much like a phone book. For each person it holds facts such as name, email address, job title, department, manager, and location. These facts are called attributes. A directory also holds groups, such as “Finance Team” or “All Contractors,” which collect people together so that rules can be applied to many people at once.
Universal Directory, often shortened to UD, is Okta’s directory service. It sits in the cloud, is built into the Okta platform, and acts as the one authoritative store that Okta uses for sign-in, access decisions, and provisioning. The word “universal” is chosen because it can bring together people from many origins, such as employees from HR, staff from Microsoft Active Directory, partners, and contractors, into a single consistent set of profiles.
Think of a large school with several offices, each keeping a private notebook of students. The sports office has one, the library has one, and the canteen has one. Universal Directory is like creating one master register at the front office. Every other office reads from that register and does not keep its own guesswork. When a student changes class, the front office updates one line and everybody sees it.
What it is not
- It is not just a login list. It holds much more than usernames and passwords. It holds the full profile that decides what each person can reach.
- It is not only a copy of Active Directory. It can connect to Active Directory, but it can also stand on its own, with no on-premises directory at all.
- It is not the same as Single Sign-On. Single Sign-On is about letting people in. Universal Directory is about knowing who the people are and what facts describe them. The two work together, but they are different jobs.
2The Problem It Solves
Without a central directory, people data splits into many copies that disagree with each other.
Picture a growing company. In its first years it keeps people in a single email system. Then it adds an HR tool, a customer relationship tool, a project tracker, a chat app, and a cloud platform. Each tool has its own user list, so every new hire must be typed into many places. This is called directory sprawl.
Inconsistent data
One system spells a department “Eng,” another says “Engineering,” a third says “R&D.” A person’s manager is correct in the HR tool but wrong in the chat app. When a rule such as “all engineers get access to the code tool” is applied, it silently misses people whose department is spelled differently.
Slow joiners, movers, and leavers
Staff changes follow a rhythm: people join, people move to new teams, and people leave. With many lists, each change is a long checklist of manual edits. Late edits mean new hires waiting for access on day one, and leavers keeping access long after they depart.
Mergers and acquisitions
When one company buys another, two completely different directories suddenly need to coexist. Rebuilding everything into one old on-premises directory can take years. A cloud directory that accepts people from several sources makes the merger much smoother.
Different kinds of people
Modern organisations serve more than full-time employees. They also include contractors, interns, partners, and sometimes customers. Each type needs different details. A contractor may need an end date and an agency name. An employee needs a cost centre. One rigid list cannot describe them all well.
Stale profile data is a security problem, not just an annoyance. If access rules depend on a department or title that is out of date, people may keep access they should have lost, or lose access they still need.
Before a central directory
- Many copies of every person
- Manual edits in each tool
- Spelling and format differences
- Unclear source of truth
With Universal Directory
- One profile per person
- Automatic updates flow outward
- Consistent attribute rules
- Clear source for each fact
3Key Words You Need
A short dictionary. Each term says what it is, why it exists, and gives a picture to remember it.
User Profile
The full record of one person: their username, email, name, and any other attributes you choose. It is one page in the master register.
Attribute
A single fact on a profile, such as department or start date. It exists so that rules and apps can make decisions from clean, named facts.
Base and Custom Attributes
Base attributes come built in, such as first name and email. Custom attributes are ones you add yourself, such as badge number or cost centre.
Profile Editor
The admin screen where you view and change what attributes exist and how they map between Okta and apps. Think of it as the form designer for your register.
Attribute Mapping
A rule that copies or transforms a value from one profile to another. It exists because each app names and formats facts differently.
Profile Master (Source of Truth)
The system that is allowed to change a person’s facts. If HR is the master, only HR edits flow in, and other changes are overwritten or blocked.
Group
A named collection of people. Groups exist so you can give access or apply policy to many people at once instead of one by one.
Group Rule
An automatic rule that places people into a group when their attributes match a condition, for example everyone whose department is Sales.
User Type
A category of person, such as employee or contractor, each with its own set of attributes. It lets one directory describe different people properly.
Okta Expression Language
A small formula language used inside mappings and group rules to build or test values, such as joining first and last name into a display name.
Directory Agent
A small program installed inside your network that securely links an on-premises directory such as Active Directory to Okta.
Provisioning
Creating, updating, and removing accounts inside apps automatically, using the facts in the directory.
Every person in Okta has a login attribute. It is the username they sign in with, and it must be unique across the organisation. By default it looks like an email address. Many other facts can be shared or changed, but the login is the person’s identity anchor.
4Architecture and Components
Where Universal Directory sits and what connects to it.
Universal Directory is at the middle of the picture. On the left are sources, the systems that know the truth about people. On the right are destinations, the apps and services that need those facts. In the middle is Okta, which stores profiles, applies mappings and rules, and passes clean data outward. It is built as a multi-tenant cloud service. That means Okta runs it for very many customers on shared, highly available infrastructure, while keeping each customer’s data separated in its own organisation.
flowchart LR
HR["HR System"] --> IMP["Import and Sync Engine"]
AD["Active Directory via Agent"] --> IMP
LDAP["LDAP Directory via Agent"] --> IMP
ADMIN["Admin Console and API"] --> UD
IMP --> UD[("Universal Directory")]
UD --> PE["Profile Editor and Mappings"]
UD --> GR["Groups and Group Rules"]
PE --> PROV["Provisioning Engine"]
GR --> PROV
PROV --> APP1["Cloud App A"]
PROV --> APP2["Cloud App B"]
UD --> SSO["Sign-On and Policy Engine"]
UD --> LOG["System Log"]
LOG --> SIEM["Security Monitoring"]
LB["Load Balancer and API Gateway at Okta Edge"] --> ADMIN
Component by component
HR systems
Tools such as Workday or other HR platforms are the best source for who works at the company, their job, and their manager. They usually act as the master for those facts.
On-premises directories
Microsoft Active Directory and LDAP directories can be connected through an Okta agent. This lets a company keep what it has while moving to the cloud gradually.
Import and sync engine
Pulls people in from sources on a schedule or on demand, matches them to existing profiles, and creates or updates records.
Universal Directory store
The profile database. It holds users, attributes, group membership, and the relationship to each connected app.
Profile Editor
Defines attributes and the mapping between the Okta profile and each app’s own profile.
Provisioning engine
Takes changes from the directory and pushes them to apps, commonly using a standard called SCIM, which describes how to create and update users across systems.
Edge, load balancing, and API gateway
Okta’s front door spreads traffic across many servers and applies limits, so a surge in one customer’s requests does not harm others.
System Log
A record of what happened, such as a profile change, a login, or a failed import. It feeds monitoring tools.
Two kinds of profile
This idea matters a lot, so it gets its own place. There is the Okta user profile, which is the central record of the person. And there is an app user profile, which is the version of that person that lives inside one app, shaped to what that app understands. When someone is given access to an app, Okta creates an app user profile and fills it by following the mappings. The directory holds the master picture, and each app holds a tailored copy.
5The User Profile and Its Attributes
What a profile contains and how you shape it.
Every Okta user profile starts with a set of built-in attributes such as login, email, first name, last name, display name, and a few contact and job fields like title, department, and manager. These are called base attributes. Administrators can add custom attributes for anything else the business needs, such as employee number, hire date, cost centre, building, or contractor end date.
Data types
Each attribute has a data type, which tells Okta what kind of value to expect. Common kinds are text, whole numbers, decimal numbers, true or false values, and dates. Some attributes can also hold a list of values, for example several roles. Choosing the right type matters because it controls what can be stored and how it can be used in rules. A start date stored as plain text cannot be compared by date, while a real date can.
Useful settings on an attribute
- Required: the profile cannot be saved without a value. Use this for facts that every person must have.
- Unique: no two people may hold the same value. Employee numbers are a classic case.
- Allowed values: a fixed list to choose from, such as a set of department names. This prevents spelling differences at the source.
- Permissions: who may see or change the value. Some attributes can be hidden from the person, shown as read-only, or made editable.
A profile is like a form at a doctor’s reception desk. Some boxes are compulsory, some boxes allow only tick-marks from a list, and some boxes are for staff use only, which the patient cannot change. Good form design stops mistakes before they enter the system.
Keep the model lean
It is tempting to add an attribute for every idea. Resist it. Each attribute must be fed by someone, kept accurate, and mapped to apps. A smaller set of well-governed attributes is far more useful than a long list that nobody maintains. Before adding an attribute, ask who owns it, where its value comes from, and which app or rule will use it.
Name custom attributes in a consistent, clear style and write down what each one means. Future administrators will thank you, and apps that receive the value will be easier to debug.
6Profile Editor and Attribute Mappings
Mappings translate the same fact between different systems.
Different systems describe the same fact differently. Okta may store a person’s full name in two parts, while an app wants one combined name. An app may call the department field “team.” A phone system may expect numbers in a special format. Attribute mapping is the translation layer that handles all this.
Directions of flow
Mappings work in two directions, and each direction is set separately:
- Okta to app: a value in the Okta profile is sent to the app profile. This is the normal direction for provisioning new accounts and for pushing updates.
- App to Okta: a value in the app profile is brought into the Okta profile. This is used when the app is the source of truth, such as an HR tool.
Transforming values
A mapping can do more than copy. Using Okta Expression Language, it can join values, change letter case, pick part of a value, or choose between options depending on a condition. For example, it can build a display name from the first and last names, or create a standard email style from a name and a company domain. Administrators write these formulas in the Profile Editor, then test them on a sample user before turning them on.
sequenceDiagram
participant H as HR System
participant U as Universal Directory
participant M as Mapping Rules
participant P as Provisioning Engine
participant A as Connected App
H->>U: 1. New hire record imported
U->>U: 2. Match or create the Okta profile
U->>M: 3. Apply attribute mappings
M-->>U: 4. Clean values such as display name
U->>P: 5. Person assigned to the app by group
P->>A: 6. Create account with mapped attributes
A-->>P: 7. Confirm account created
P-->>U: 8. Record app user profile status
Mappings are like a travel interpreter. The traveller says the same thing, but the interpreter turns it into the language and customs of each country. The message is unchanged, but each listener understands it perfectly.
A wrong mapping can spread bad data to every connected app very quickly. Always test mappings on one sample user first, and review the preview before applying changes to everybody.
7Profile Mastering and Sources of Truth
When two systems disagree about a fact, which one wins?
Whenever a person’s facts exist in more than one place, there must be a clear answer to “who is allowed to change this?” That system is the profile master, sometimes called the source of truth. Without a clear master, two systems keep overwriting each other, and data flips back and forth in a confusing loop.
Who can be the master?
- Okta itself. Profiles are created and edited directly in Okta or through its API. Good for small organisations, contractors, or people with no other system of record.
- A directory. Active Directory or LDAP holds the truth, and Okta mirrors it. Fields mastered in the directory usually appear as read-only in Okta.
- An application. Usually an HR system, which is the most trustworthy place to know who is employed, their title, their manager, and their start and end dates.
Attribute-level sourcing
Real organisations rarely have one master for everything. HR may be right about job title and manager, while the directory is right about the account name and group membership, and Okta may be right about a mobile phone entered by the person. Okta supports choosing the source per attribute, so each fact comes from the system best placed to know it. When several sources can supply the same attribute, a priority order decides which one wins.
flowchart TD
Q["Which system should master this attribute?"] --> A{"Is there an HR system of record for it?"}
A -- Yes --> HR["Make HR the master"]
A -- No --> B{"Does a directory already own it?"}
B -- Yes --> DIR["Make the directory the master"]
B -- No --> C{"Does the person or an admin maintain it directly?"}
C -- Yes --> OK["Make Okta the master"]
C -- No --> D["Decide an owner first, then configure it"]
A newspaper has one editor for the sports page and a different editor for the weather page. Each editor has the final word on their own page. No single editor decides everything, and nobody edits the other’s page, so the paper stays consistent.
Matching people during import
When Okta imports from a source, it must decide whether each incoming person is someone new or someone it already knows. This is done with matching rules, which compare things like username, email, or first and last name. Good matching rules prevent duplicate profiles. Weak ones create two profiles for one human, which later causes confusing access.
8Groups, Group Rules, and Group Push
Groups turn people data into access decisions at scale.
A group is a named set of users. Groups exist because it is far easier to say “the Finance group can use the accounting app” than to list every finance employee by name. When the group changes, access changes with it.
Types of groups
Okta groups
Created and managed inside Okta. Members are added by hand, by rule, or by an import. Most day-to-day groups are of this kind.
Directory and app groups
Groups that come from Active Directory, LDAP, or an app. Okta can read them, and membership is controlled at the source.
Built-in Everyone group
Every user is automatically part of it. It is useful for company-wide access but should be used with care, since it reaches absolutely everybody.
Group rules: groups that fill themselves
A group rule watches attributes and places users into a group when a condition is true. For example, a rule can say that anyone whose department is Sales and whose user type is employee joins the Sales group. When a person moves from Sales to Marketing, the rule notices and moves them. This is how the “mover” problem is solved without a manual ticket.
HR updates the person’s department
The change arrives in Universal Directory through the import or integration.
Group rules are checked
Okta compares the new department value with the conditions in each rule.
Membership changes
The person leaves the old group and joins the new one automatically.
App access follows
Apps assigned to the old group are removed, and apps assigned to the new group are added, with accounts created or deactivated as needed.
Group Push
Some apps keep their own groups. Group Push copies an Okta group, and its members, into the app so the app’s own groups stay in step with Okta. This keeps permissions inside the app aligned with the central directory.
Group rules apply when a profile is created or changed, and large changes can take a short while to settle. Do not be alarmed if membership is not updated the very second you edit a rule. Check again after a few minutes.
9User Types
Different people need different profiles.
By default, Okta has one kind of user profile. Real life needs more. An employee needs a manager, a cost centre, and a start date. A contractor needs an agency name and a contract end date. A partner may need a company name and a sponsor inside your organisation. With user types, an administrator can create several profile designs in the same Okta organisation, each with its own attributes, mappings, and sometimes its own password and sign-in rules.
A hospital uses different forms for patients, visitors, and staff. Each form asks only the questions that make sense for that group. A visitor is not asked for a salary, and a staff member is not asked for a ward number.
Scenario: employees and contractors
A company creates two user types. Employees carry an employee number and manager, and are mastered by the HR system. Contractors carry an agency name and an end date, and are created by a business sponsor in Okta. A group rule uses the end date to remove contractor access automatically on the day the contract finishes, so nobody has to remember to do it.
Why this matters for safety
Separate user types make it easier to apply the right controls to the right people. Contractors can be given stricter sign-in rules or fewer apps without touching the rules for employees. And because contractor profiles carry an end date, forgotten accounts are less likely to linger.
10Connecting Directories and Apps
How Okta joins Active Directory, LDAP, HR systems, and the apps your people use.
Active Directory
Many organisations still run Microsoft Active Directory in their own data centres. Okta connects to it through a lightweight agent installed on a server inside the network. The agent makes an outbound secure connection to Okta, so no inbound doors need to be opened. Okta then imports users and groups from Active Directory into Universal Directory. People can also sign in with their familiar Active Directory password. Okta supports delegated authentication, where Okta passes the check to Active Directory instead of storing the password itself, and also supports password synchronisation as another choice.
LDAP directories
LDAP is a long-standing standard for talking to directories. Okta can import from an LDAP directory through an agent in a similar way. Going the other direction, the LDAP Interface lets older applications that only know how to speak LDAP use Universal Directory as their user store. This is very helpful for legacy tools that cannot be changed. Okta also offers a RADIUS agent so network equipment such as VPNs can check logins against Okta.
HR systems as sources
Okta has ready-made integrations for popular HR platforms, including Workday and others. When HR hires someone, the integration can create the Okta profile, fill in the facts, and start provisioning with no human typing. When HR ends employment, the same integration begins the removal. Many teams call this HR-driven identity, because the HR record starts and stops the whole chain.
Cloud apps
For cloud apps, Okta uses ready-made connectors from its catalogue, many of which use SCIM to create, update, and deactivate accounts. Examples of well-known apps that can be connected this way include Slack, Salesforce, Google Workspace, Microsoft 365, and many others. The directory remains the single place where facts are changed, and each app is kept up to date by provisioning.
| Connection | Direction | Typical use |
|---|---|---|
| HR system to Okta | Into Universal Directory | Start and stop the lifecycle from real HR events |
| Active Directory to Okta | Into Universal Directory | Keep an existing directory while moving to the cloud |
| LDAP directory to Okta | Into Universal Directory | Import users from older directory services |
| Okta to LDAP apps | Out through LDAP Interface | Let legacy apps use Okta as their user store |
| Okta to cloud apps | Out through provisioning | Create, update, and remove accounts automatically |
11Data Flow and User Lifecycle
From the first import of a new hire to the removal of a leaver.
Every person in Okta has a status, which tells you where they are in their life with the organisation. Understanding these statuses makes troubleshooting much easier.
stateDiagram-v2
[*] --> Staged
Staged --> Provisioned: Activation started
Provisioned --> Active: User sets credentials
Active --> Suspended: Temporary pause
Suspended --> Active: Access restored
Active --> LockedOut: Too many failed attempts
LockedOut --> Active: Unlocked
Active --> Deprovisioned: Deactivated
Suspended --> Deprovisioned: Deactivated
Deprovisioned --> [*]: Deleted
Staged
The profile exists but the person cannot sign in yet. This is common when profiles are prepared ahead of a start date.
Provisioned
Activation has begun and the person is waiting to finish setting up their sign-in, for example by choosing a password.
Active
The normal working state. The person can sign in and use the apps assigned to them.
Suspended
Access is paused but the profile is kept, for instance during leave. The person can be restored later.
Locked out
Too many wrong attempts triggered a lock. A policy or an administrator can unlock the account.
Deprovisioned
The account is deactivated. App accounts are removed or disabled, and the profile can later be deleted.
The joiner, mover, leaver rhythm
- Joiner: HR creates the person. The profile flows into Universal Directory, group rules place them in the right groups, and apps are provisioned so that access is ready on day one.
- Mover: HR updates a department or manager. Mappings update the facts, group rules move the person between groups, and app access changes automatically.
- Leaver: HR marks the end of employment. The profile is suspended or deactivated, sessions are ended, and app accounts are removed or disabled across the board.
Many teams choose to suspend or deactivate on the last working day rather than wait for a delayed HR update. Agree on the exact timing with HR and security, and write it into your process so nobody is surprised.
12Advantages, Disadvantages and Trade-offs
A central directory brings large benefits and a few responsibilities.
Advantages
- One consistent profile: a single, trusted view of each person.
- Automation: joiners, movers, and leavers are handled with little manual work.
- Flexible sources: HR, directories, and Okta itself can all contribute.
- Cloud based: no directory servers of your own to patch or scale.
- Precise control: attribute-level sourcing and permissions fit real organisations.
- Supports mixed populations: user types cover employees, contractors, and partners.
- Better security: clean attributes make access rules accurate.
Disadvantages
- Design effort: good attribute models, mappings, and masters take real planning.
- Garbage in, garbage out: poor source data is copied faithfully to every app.
- Central dependency: many systems rely on one service being healthy.
- Change blast radius: a bad mapping or rule can affect many people at once.
- Source conflicts: unclear mastering leads to values being overwritten.
- Licence and limits: features and quotas depend on your plan, so check them.
Thinking in trade-offs
The main trade is between speed of change and safety of change. Automation makes updates instant, which is wonderful when the data is right and painful when it is wrong. Teams that succeed put review steps before large changes, test on small groups first, and keep an easy way to undo. A second trade is between a rich profile and a simple profile. More attributes allow smarter rules, but each one needs an owner and a source.
Retiring an on-premises directory is a big project. Do not remove Active Directory just because Universal Directory is in place. Many apps, servers, and devices may still depend on it. Move step by step, and confirm what depends on it before switching anything off.
13Security of Universal Directory
The directory decides who people are and what they may reach, so it needs strong protection.
Universal Directory holds personal data and drives access decisions. If an attacker could change a profile, they might be able to join a privileged group or alter a contact detail used for account recovery. Protecting it means protecting both the data and the people who can change it.
Main risks
Over-powered administrators
Too many people with full admin rights widens the chance of mistakes and of an attacker finding a strong account to take over.
Attribute tampering
If a person can edit an attribute that drives group rules, such as department, they might move themselves into a group with more access.
Weak recovery paths
Attackers target help desks and recovery steps to take over an account. Contact details in the profile must be trustworthy.
Stolen API tokens
An automation token with wide rights can read or change many profiles. If it leaks, the damage can be large.
Over-sharing attributes
Sending more personal data to an app than it needs creates privacy exposure and may break data protection rules.
Orphan and stale accounts
Accounts for people who left, or for contractors whose end date passed, remain open if the lifecycle is not automated.
The defences that matter most
- Least privilege for admins. Okta offers different administrator roles, such as read-only, help desk, group, and organisation administrators, plus custom roles. Give each person only the role they need, and keep full administrator access for a very small number of people.
- Strong sign-in for administrators. Require multi-factor authentication, ideally with phishing-resistant methods, for anyone who can change the directory.
- Lock attributes that drive access. Make department, manager, and similar fields read-only for users, and master them in HR so they cannot be self-edited.
- Share only what is needed. Map only the attributes an app genuinely needs. Less data shared means less data exposed.
- Careful recovery rules. Verify identity strongly before resetting factors or changing recovery details.
- Protect API tokens. Store them in a secrets vault, limit their rights, rotate them, and watch their use.
- Automate leaving. Tie end dates and HR termination events to automatic suspension and removal.
- Review regularly. Audit privileged groups, admin roles, and unused accounts on a schedule.
The directory is like the key cabinet of a large building. The more people who can open the cabinet and change which key fits which door, the more risk there is. A good building keeps the cabinet locked, lets only a few trusted staff handle it, and logs every time it is opened.
14Monitoring, Logging and Metrics
You cannot trust a directory you cannot observe.
Okta records activity in its System Log. Every important event, such as a profile change, an import, a group change, a failed login, or an administrator action, leaves a record. Security and operations teams can search these records inside Okta, call them through an API, or stream them to external tools for long-term storage and analysis. Okta supports log streaming to destinations such as Splunk Cloud and Amazon EventBridge, so the data can sit beside the rest of an organisation’s security logs.
What to watch for
Admin role changes
Someone granted a powerful administrator role, especially out of hours, deserves a quick review.
Mass profile or group changes
Large numbers of changes in a short time can mean a faulty import, a bad rule, or misuse.
Import and sync failures
Repeated failures mean the directory is drifting from its source. Fix them before the data goes stale.
Changes to privileged groups
Anyone added to a group that grants broad access should trigger an alert and a record of who approved it.
Factor resets and recovery
Unusual numbers of resets for one team or one person can hint at social engineering.
API token activity
A token used from a strange place, or suddenly making many calls, may have been stolen.
Health metrics
Operations teams also track the health of the directory itself: how long imports take, how many records fail, how many users are in each status, how many accounts have no manager or no department, and how close the organisation is to API rate limits. Okta limits how fast an organisation may call its APIs, to protect all customers, so bulk scripts should be written to slow down and retry politely when they are told to wait.
Data quality is itself a metric worth measuring. A simple weekly report that counts profiles with missing required facts, such as manager or department, will quietly prevent many access problems.
15Design Patterns and Anti-patterns
Habits that keep a directory healthy, and habits that slowly spoil it.
Patterns worth copying
HR as the root of truth
Let the HR system master identity facts such as name, title, manager, and employment dates. Every other change flows from HR events.
Attribute-driven groups
Build groups with rules based on clean attributes instead of adding people by hand. Access then follows the person’s real role.
Role-based bundles
Create a small number of well-named groups that each represent a job role, and attach the right apps to each one.
Separate types for separate people
Use user types for employees, contractors, and partners so each gets the right attributes and controls.
Test in a preview organisation
Try new mappings and rules in a non-production Okta organisation first, then promote them with care.
Expiry by design
Give temporary people an end date and let a rule remove their access when that date arrives.
Anti-patterns to avoid
What it looks like
Two systems, for example Active Directory and an HR tool, are both allowed to change the same attribute, with no priority order.
Why it hurts
Each import overwrites the other. Values flip back and forth, and nobody can say which is correct.
Better approach
Choose one master per attribute, write the decision down, and set a clear priority order wherever several sources can supply the same fact.
What it looks like
A group rule or mapping is changed directly in production for everyone, with no test and no review.
Why it hurts
A small typo can remove access for hundreds of people or grant access to the wrong ones, and the error spreads to every connected app.
Better approach
Test on a sample user or a small pilot group, review the preview, make changes in quiet hours, and keep a note of the old setting so it can be restored quickly.
What it looks like
People can edit their own department or title, and those fields drive group membership and app access.
Why it hurts
A person can promote themselves into a group with more access, simply by typing a new value.
Better approach
Make access-driving attributes read-only for users and master them in HR or another controlled source.
What it looks like
Dozens of one-off groups and custom attributes are created for every request, and nobody records who owns them or why they exist.
Why it hurts
The directory becomes cluttered. Nobody dares to delete anything, access becomes hard to explain, and audits turn painful.
Better approach
Use a naming standard, record an owner and purpose for each group and attribute, and review and retire unused ones on a schedule.
16Best Practices and Common Mistakes
A short checklist for planning and running Universal Directory well.
Best practices
- Design before you build. List the attributes you need, who owns each, and where each value comes from. Draw the picture first.
- Clean the sources first. Fix duplicates, missing managers, and inconsistent department names before importing. Okta will copy the mess faithfully otherwise.
- Use lists of allowed values. Where an attribute should be one of a few choices, restrict it, so spelling variations never appear.
- Pick masters per attribute. Do not assume one system owns everything.
- Start small. Pilot with one team or one app, learn, then widen.
- Automate lifecycle events. Connect HR to Okta and Okta to apps so joiners, movers, and leavers need no tickets.
- Keep admin access tight. Use specific roles, strong sign-in, and regular reviews.
- Log and alert. Stream the System Log to your security tools and alert on privileged changes.
- Document everything. Write down what each attribute, group, and rule is for, who owns it, and when it was last reviewed.
- Plan for rollback. Before any bulk change, know how to undo it.
Common mistakes
| Mistake | What goes wrong | Simple fix |
|---|---|---|
| No clear profile master | Values are overwritten back and forth | Set one master per attribute with a priority order |
| Free-text department field | Group rules miss people because of spelling differences | Use allowed values and control the source |
| Weak matching rules on import | Duplicate profiles for one person | Match on a stable, unique attribute such as employee number |
| Too many super administrators | Higher risk of mistakes and takeover | Use least-privilege roles and review them |
| Everyone group gives access to sensitive apps | Every person, including contractors, gets access | Assign sensitive apps to specific, rule-based groups |
| Skipping mapping tests | Bad values reach every app at once | Preview on a sample user before applying |
| Ignoring contractor end dates | Accounts survive long after contracts end | Store an end date and automate removal |
| Over-sharing attributes with apps | Unneeded personal data is exposed | Map only what each app needs |
17Real-World Usage Scenarios
Three illustrative situations that show how organisations put Universal Directory to work.
The scenarios below are illustrative examples built from common patterns, not accounts of any one named customer. They use real, well-known systems so that the pieces are easy to recognise.
Scenario 1: A fast-growing company hires every week
A software company hires dozens of people each month. The recruiting team records each offer in Workday. When the person accepts, the integration creates a staged profile in Universal Directory with name, title, manager, and start date. On the start date, the profile becomes active. Group rules read the department and job family and place the person in the right groups. Those groups carry assignments for Slack, Google Workspace, Salesforce, and the code repository. By the time the new hire opens a laptop, accounts already exist and the right access is in place. No help desk ticket was needed.
Scenario 2: A company moving away from on-premises servers
A manufacturer has run Microsoft Active Directory for many years and wants to adopt cloud apps without a risky big-bang move. It installs the Okta agent, imports users and groups, and lets staff sign in to cloud apps through Okta while still using their familiar password. Over time, HR becomes the master for job details, and Okta becomes the master for cloud groups. Older apps keep working through Active Directory and the LDAP Interface. Each year, fewer apps need the old directory, and the team retires pieces of it only once nothing depends on them.
Scenario 3: A company after an acquisition
A retail group buys a smaller business that has its own directory and its own apps. Instead of forcing the new staff into the old environment, the group connects the acquired company’s directory as another source feeding Universal Directory. Staff from both companies appear as consistent profiles. User types separate the two populations where their needs differ. Shared apps, such as email and a company intranet, are assigned by group, and each business keeps its own specialised tools until a proper plan is ready to merge them.
Scenario 4: Managing contractors and partners
A consulting firm brings in hundreds of short-term contractors. Each contractor profile is created by a sponsor and has a contract end date. A group rule watches the date. On the end date the contractor is moved out of project groups and suspended, and app accounts close automatically. Audit reports show exactly who had access, when, and who sponsored them.
18Frequently Asked Questions
Quick answers to the questions people ask most.
19Summary and Key Takeaways
The whole story of Universal Directory in a few lines.
Universal Directory is Okta’s cloud directory. It keeps one trusted profile for each person, takes facts from the best source for each attribute, shapes them with mappings, groups people with rules, and passes clean data to the apps they use. It turns the old, slow, manual world of many disagreeing lists into one connected flow that starts with real HR events. In return, it asks for careful design, tight administrator control, and good monitoring, because so much depends on it.
Key Takeaways
- One central profile per person. Universal Directory stores users, attributes, and groups in the Okta cloud, ending the drift between many separate lists.
- Know the master of every fact. Choose HR, a directory, or Okta as the source per attribute, and set a priority order so values never fight each other.
- Mappings translate between systems. The Profile Editor and Okta Expression Language shape values for each app, and every mapping should be tested on a sample user first.
- Groups and rules automate access. Attribute-driven group rules solve joiners, movers, and leavers without manual tickets.
- User types describe different people. Employees, contractors, and partners can each have their own attributes and controls in one organisation.
- Protect the directory itself. Use least-privilege admin roles, strong sign-in for administrators, read-only access-driving attributes, and share only the data each app needs.
- Observe and improve. Stream the System Log, alert on privileged changes, track data quality, document every rule, and always plan how to roll back a change.