Before we connect anything, let us understand the thing being connected.

A directory is an organized list of the people, groups and devices that belong to an organization. It stores facts about each person, such as a name, an email address, a job title, a manager, and the groups they belong to. It also helps check passwords when someone tries to sign in. In many companies this list is kept on servers inside the company’s own buildings or data centers. The most famous example is Microsoft Active Directory, often shortened to AD. Another common kind speaks a language called LDAP, which stands for Lightweight Directory Access Protocol. A protocol is simply an agreed way for computers to talk to each other.

What lives inside a directory

Each person in a directory is stored as an entry, also called an object. An entry has attributes, which are the small facts about that person. A first name is an attribute. So is an email address, a department, or a phone number. Entries are arranged in folders called organizational units, or OUs, which usually follow the company’s shape, such as one folder for each office or department.

The pain of two lists is the reason this feature exists.

Imagine that Okta had its own list of users, and the company’s directory had another list. A new person joins, and the help desk adds them to the directory. Someone must also remember to add them to Okta. A person leaves, and someone must remember to remove them from both. Sooner or later, one list gets out of date. A former employee keeps access to a cloud tool for weeks, and a new joiner cannot start work because the second list was forgotten.

Passwords make it worse. If people must keep one password for the office network and another one for Okta, they will forget one of them, reuse them, or write them on sticky notes. Each of these habits creates risk.

What integration promises

Directory integration means connecting your existing directory to Okta so that the two stay in step. Okta reads the people and groups from your directory, creates matching user profiles in the cloud, and keeps them updated. People can also use the password they already know. There is one source of truth, and changes flow from it automatically.

The big picture first, the details later.

Okta is an identity provider, which means it is the trusted service that knows who everyone is and decides whether they may enter an app. To do that job well, Okta needs a good list of people. That list can come from several places. In the Okta admin console, a section called Directory Integrations is where an administrator connects those places.

The main kinds of connection

What “basic” means in this guide

This guide covers the foundation: the core idea, the most common setup with Active Directory, a short look at LDAP, and the habits that keep an integration healthy. It skips rare and highly customized setups so that you can build a solid mental picture first. Once the basics feel natural, the advanced options become much easier to learn.

Ten small ideas explain almost everything in this topic.

Source of truth in one paragraph

A source of truth is the one place that everyone agrees is correct. In a directory integration, your on-site directory is very often the source of truth for people. Okta reads from it and does not argue with it. If a phone number is wrong, you fix it at the source, and the fix travels to Okta on the next sync.

Why an agent is needed

Your directory lives inside your private network, behind firewalls, on purpose. Okta lives in the cloud. The two cannot simply call each other across the internet. The agent sits inside your network and opens a safe outgoing connection to Okta, which acts like a secure tunnel. That one design choice is what makes the whole setup safe and simple to approve with network teams.

Who are the players, and what does each one do?

flowchart LR
  AD["On-Premises Active Directory"] --> AG["Okta AD Agent on a Member Server"]
  AG -->|"Outbound HTTPS only"| OK["Okta Cloud"]
  OK --> UD["Universal Directory"]
  UD --> AP["Cloud and Web Applications"]
  U["Employee"] --> OK
  ADM["Okta Administrator"] --> OK

The parts, one by one

The on-site directory is where your people already live. For most companies this is Active Directory, running on servers called domain controllers. A domain controller is a server that answers questions about who is allowed to do what inside the company network.

The Okta AD Agent is a small Windows service. It is installed on a server that is part of your domain, and many companies choose a dedicated member server instead of a domain controller itself. The agent reads from the directory, and it carries password checks and other requests. It makes an outgoing connection to Okta over normal secure web traffic, so you usually do not need to open any inbound doors in your firewall.

Okta Cloud is the service that receives the data, applies your rules, and builds user profiles. Universal Directory is the part of Okta that stores those profiles. Applications are the cloud tools that people use every day. They trust Okta to say who the person is. The administrator is the person who configures all this, and the employee is the person who simply signs in.

Why outbound only matters

Security teams worry about any opening in the network wall. With this design, nothing from the internet has to walk in. The agent reaches out, and answers travel back on the same connection. That is a much smaller risk than leaving a door open for the cloud to knock on.

The journey from nothing to a working link takes careful planning more than clever clicking.

Choose a clean way to name users

Every person needs a unique sign-in name in Okta. Companies commonly build it from the email address or from the directory’s user principal name, a login name that looks like an email address. Pick a rule that does not change often and that never repeats. A name rule that clashes will cause confusing errors later.

Reading a directory is simple in idea and careful in practice.

sequenceDiagram
  autonumber
  participant OK as Okta Cloud
  participant AG as AD Agent
  participant DC as Domain Controller
  OK->>AG: Request an import through the open outbound channel
  AG->>DC: Read users and groups in the chosen folders
  DC-->>AG: Return entries and their attributes
  AG-->>OK: Send the data securely
  OK->>OK: Match people, map attributes, create or update profiles
  OK->>OK: Record the results in the system log

Walking through the diagram

The agent keeps a standing secure connection to Okta. When an import starts, either on a schedule or because an administrator pressed a button, Okta passes the request down that connection. The agent then asks the domain controller for the people and groups inside the folders you chose.

The domain controller replies with entries and their attributes. The agent forwards them to Okta, still over the secure connection. Okta then does the careful work. It compares each incoming person with the people it already knows. It applies your attribute mapping so that facts land in the right fields. It creates new profiles, updates changed ones, and, depending on your settings, deactivates people who have disappeared or been disabled.

Full imports and incremental imports

A full import reads everything in scope and compares it to what Okta has. It is thorough but slower. An incremental import only looks at what changed since last time. It is fast and light, which makes it good for frequent runs. Many teams run quick incremental imports often and a full import less often as a safety net.

Three words that sound alike and do three very different jobs.

Matching: is this the same person?

When the import finds a person in the directory, Okta asks whether that person is already in its list. It compares something that should be unique, such as the username or the email address. If it finds a match, it links the two and does not create a copy. If there is no match, it creates a new profile. A poor matching rule leads to duplicates, and duplicates lead to confused users who have two accounts and two sets of access.

Mapping: which fact goes where?

Directories and Okta name their facts differently. One calls the email address “mail” while the other calls it “email”. Attribute mapping is a translation table. You tell Okta that the directory’s department fact fills the Okta department field, and so on. Mappings can go in one direction or both, depending on your design.

Mastering: who wins a disagreement?

If two sources describe the same person differently, one must be the boss. This is called profile mastering. In a basic setup, the on-site directory is master. Edits made directly in Okta for those facts are either blocked or overwritten on the next import, so there is no tug of war.

How can people keep the password they already know?

After the import, Okta knows who your people are. But what about their passwords? In a common setup called delegated authentication, Okta does not keep its own copy of the directory password. Instead, when a person signs in to Okta, Okta hands the password check to your directory through the agent. The directory says valid or not valid, and Okta acts on that answer.

sequenceDiagram
  autonumber
  participant U as User
  participant OK as Okta
  participant AG as AD Agent
  participant DC as Domain Controller
  U->>OK: Type username and directory password
  OK->>AG: Pass the sign-in request
  AG->>DC: Ask the directory to check the password
  DC-->>AG: Valid or not valid
  AG-->>OK: Send the result
  OK-->>U: Sign in or show an error

Why companies like this

The directory stays the one place where passwords are set, changed and locked. If someone is disabled in the directory, they cannot get into Okta either. If a person is locked out after too many wrong tries, the same rule applies in Okta. People remember one password, and the security team enforces one set of password rules.

Other pieces that often come along

Many organizations pair directory sign-in with a second proof, such as an approval on a phone app, so that a stolen password is not enough on its own. Some also set up desktop single sign-on, which can let a person who is already signed in to their company computer reach Okta without typing anything again. Some companies allow changes of password to flow from Okta back into the directory, while others keep it strictly one way. These are design choices, and each has trade-offs that your team should discuss.

Importing everyone is rarely the right answer. Importing the right people is.

Scope with organizational units

You can tell Okta which folders to read. For example, you may choose the folders for full-time staff and contractors, but skip the folders for test accounts, shared mailboxes and old archived users. This is called scoping. A tight scope keeps Okta clean and limits risk.

Groups drive access

Directory groups are also imported. Once they are in Okta, they become a powerful steering wheel. You can say that everyone in the “Sales” group receives the customer-relationship app, and everyone in “Engineering” receives the code repository. When someone changes team in the directory, their group changes, and their app access follows by itself on the next sync.

Two different ideas that sound the same. Learn to tell them apart.

So far we have talked about Active Directory. Not every company uses it. Some use other directories that speak LDAP, such as certain open-source or vendor directories. Okta can connect to these too, using a helper called the Okta LDAP Agent. It works in the same spirit as the AD Agent: installed inside your network, making outgoing connections, reading people and groups, and passing password checks.

The second idea: Okta acting like an LDAP server

There is a twist. Some older apps and devices, such as certain network gear, print servers and legacy tools, were built long ago to sign people in by asking an LDAP server. They cannot speak the modern web sign-in language. For these, Okta offers a feature called the Okta LDAP Interface. It lets Okta answer LDAP questions, so the old app thinks it is talking to a normal LDAP server while Okta does the real work behind the curtain.

flowchart LR
  subgraph IN["Direction 1 - bring people into Okta"]
    L["LDAP Directory"] --> LA["Okta LDAP Agent"] --> OK1["Okta"]
  end
  subgraph OUT["Direction 2 - let old apps ask Okta"]
    APP["LDAP Based Application"] --> LI["Okta LDAP Interface"] --> OK2["Okta"]
  end

A simple way to remember

If the question is “I already have a directory and want Okta to read it,” you want an agent integration. If the question is “I have an old app that only speaks LDAP and I want it to use Okta,” you want the LDAP Interface. Mixing them up is one of the most common beginner mistakes.

Follow one employee from the first day to the last.

flowchart LR
  J["Joiner: account created in the directory"] --> I["Import creates the Okta user"]
  I --> A["Apps assigned through groups"]
  A --> M["Mover: group or attributes change"]
  M --> A
  A --> L["Leaver: account disabled in the directory"]
  L --> D["Okta deactivates the user at the next sync"]

The joiner

A new hire is added to the directory by HR or IT. At the next import, Okta sees the new entry and creates a matching profile. Because the person is in certain groups, they receive the right apps automatically. On day one they can sign in with their directory password.

The mover

People change teams, offices and titles. Each change is made once in the directory. The next import updates the Okta profile and shifts the groups. App access that depends on those groups shifts too. This is the biggest time saver in the whole system, because moves are easy to forget when each app is handled by hand.

The leaver

When someone leaves, the directory account is disabled. At the next import, Okta notices and, depending on your settings, deactivates the matching profile. Sessions end, and the person can no longer reach connected apps. Accounts in other apps can also be removed or suspended through provisioning.

Every design trades something away. Here is an honest balance sheet.

Comparing where the list of people can live

The big trade-off: freshness versus load

If you import very often, changes arrive fast, but you add work for the directory and the agent. If you import rarely, the load is low, but leavers keep access longer. Most teams pick a middle path with frequent light imports and a regular full check.

The agent has a trusted place inside your network. Treat it that way.

Threat 1: A compromised agent server

The server that runs the agent can read parts of your directory and handle password checks. If an attacker takes it over, they gain a strong foothold. Defenses include keeping the server dedicated and patched, limiting who can log on to it, and monitoring it closely, as you would a domain controller.

Threat 2: An over-powered service account

The agent uses a service account. If that account has more rights than it needs, a leak becomes a disaster. Follow the principle of least privilege, which simply means giving each account only the permissions it truly needs. Use a long random password and protect it well.

Threat 3: Importing the wrong accounts

If powerful accounts, such as administrators or old service accounts, are imported by mistake, they can be assigned apps they should never touch. Careful scoping keeps them out.

Threat 4: Weak or unencrypted connections

For LDAP in particular, an unprotected connection can reveal secrets to anyone watching the network. Always use the encrypted option, and keep certificates valid.

Threat 5: Delayed removal of leavers

A former employee who keeps access for even a day is a risk. Use quick imports, and for sensitive cases use direct deactivation in Okta at once.

Threat 6: Stolen passwords

Because the directory password now opens many cloud apps, a stolen password is worth more to an attacker. Add a second proof, such as an approval on a phone app, and use rules that ask for extra proof in risky situations.

If the agent is the bridge, plan for the day a bridge is closed.

Because the agent carries both imports and, in delegated sign-in, every password check, it should never be a single point of failure. A single point of failure is one part that, if it breaks, stops the whole system. The usual fix is to install more than one agent on separate servers, ideally in different places and talking to different domain controllers.

flowchart TD
  OK["Okta Cloud"] --> A1["Agent 1 on Server A"]
  OK --> A2["Agent 2 on Server B"]
  A1 --> DC1["Domain Controller 1"]
  A2 --> DC2["Domain Controller 2"]

What can fail, and what happens

Have a break-glass plan

Sensible companies keep a small number of specially protected emergency administrator accounts that do not depend on the directory. They are used only if the normal path is broken, and every use is checked afterwards.

If nobody looks at the lights on the dashboard, a quiet failure stays quiet.

Okta writes a record of important events into its system log. Imports, agent connections, sign-in successes and failures, and changes to users are all written down. The admin console also shows the status of each agent, so you can see at a glance whether it is connected.

What to keep an eye on

Useful numbers to track over time

Beyond individual alerts, teams track simple health numbers. Examples include how long each import takes, how many users were created, changed and deactivated in each run, how many sign-ins fail through the directory, and how many agents are healthy. Slow, steady changes in these numbers often show a problem long before users complain.

Watch the directory side too

The directory and the agent server need their own health checks. Disk space, memory, time settings and security patches on the agent server all matter. A server with the wrong clock can cause strange secure-connection errors that look like Okta problems but are not.

Most problems have simple causes. Check these before anything else.

A calm step-by-step routine

Habits that work well, and habits that cause trouble.

Patterns that work

Anti-patterns that cause trouble

A short checklist for the person setting this up.

Before you start

• Clean the directory first. Remove old accounts, fix missing emails and make usernames unique.
• Write down your plan: folders in scope, master for each fact, and naming rules.
• Agree on the import schedule and on how urgent leavers will be handled.
• Talk to the network team about outgoing secure connections and any proxy.

While you build

• Use a dedicated, least-privilege service account.
• Install at least two agents on separate servers.
• Pilot with a small group and review the first import by eye.
• Turn on a second proof for sign-in, so that a stolen password is not enough.
• Document every setting, including why it was chosen.

After go-live

• Watch the agent status and the system log every day at first, then through alerts.
• Rotate the service account password before it expires.
• Patch the agent servers and keep their clocks accurate.
• Review groups, folders and access at regular intervals.
• Practice an urgent removal and a break-glass sign-in before you need them.

Common mistakes

Where this idea shows up in daily working life.

Okta is used by organizations of many sizes around the world, and a large share of them already own an on-site directory before they begin. The scenarios below are typical examples of how organizations in different fields apply the same ideas.

Lessons from real projects in the industry

Teams that report smooth directory projects tend to share the same habits. They clean data first, scope carefully, run more than one agent, pilot with a small group, and watch the logs. Teams that report painful projects tend to rush, import everything, and discover the problems after thousands of users are affected. The lesson is that preparation matters more than clever configuration.

Getting people into Okta is half the story. Getting them into the apps is the other half.

Once your people are inside Okta, the next question is what they can reach. Many apps keep their own list of users. A project tool, for example, needs to know that Asha exists before Asha can open a board. Provisioning is the automatic creation, updating and removal of those app accounts, based on what Okta knows. Many apps accept these instructions through a common standard called SCIM, which stands for System for Cross-domain Identity Management. It is simply an agreed set of messages that say “create this person,” “change this fact,” or “turn this person off.”

Three actions that matter

How the chain fits together

The full chain is easy to say in one breath. The directory is the source. Okta imports it. Groups in Okta decide which apps a person should have. Provisioning then makes sure the right accounts exist in those apps. If any link is weak, the chain gives odd results, such as a person who can sign in to Okta but finds no account waiting in the app.

A made-up story ties all the pieces together.

Asha is a new analyst joining a company that uses Active Directory and Okta. Follow her through each stage. The names and details here are invented for teaching.

What the story shows

At no point did anyone type Asha into Okta by hand. At no point did anyone visit each app to add or remove her. Every change was made once, in the directory, and the rest followed. This is the whole value of the integration, and it becomes more precious as the company grows.

There is more than one way to decide who checks the password.

We met delegated authentication earlier. It is the most common choice for companies that keep their directory, but it is not the only one. The right answer depends on where your company wants passwords to live in the long run.

A word about desktop single sign-on

Some companies also set up desktop single sign-on. When a person is already signed in to a company computer on the company network, Okta can recognize them and let them in without asking for a password again. It feels smooth, but it relies on the computer and network being trustworthy, so many companies pair it with extra checks for sensitive apps.

Good projects are decided on paper before they are decided in the console.

Most directory integration problems are planning problems in disguise. A small set of questions, answered early and written down, saves weeks later. Here are the questions in four groups.

Roll out in phases

Keep this chapter handy. Every word used in the guide is explained here.

Directory words

Okta words