One sentence version: Okta borrows your directory as its source of people and as its judge of passwords.

A directory is a central database of people and things in an organization, such as users, groups, computers, and the rules that apply to them. Active Directory (AD) is Microsoft’s directory, and it runs inside most mid-size and large companies. LDAP, short for Lightweight Directory Access Protocol, is a common language that programs use to ask a directory questions like “Does this user exist?” and “Is this password correct?” Active Directory speaks LDAP, and so do many other directories.

Okta is an identity provider, which means it is a service that proves who people are to many apps at once. Directory integration is the link between Okta and your directory. It does two basic jobs. First, it imports users and groups so Okta knows who exists. Second, it uses delegated authentication, which means Okta asks the directory to check the password instead of storing the password itself.

A handful of terms will make every later chapter easy to read.

Directory talk is full of short, odd-looking words. Here are the ones you will meet most often, explained in plain language.

Active Directory versus other LDAP directories

Active Directory is the most common case, so it gets the most attention in Okta. But some companies run other LDAP directories, such as OpenLDAP or an enterprise directory server. Okta supports these through a separate LDAP agent. The ideas are almost the same: import people, then ask the directory to check passwords. The main difference is the data layout, because each directory names its fields a little differently.

The problems this integration removes are the same ones every growing company runs into.

Without integration, an IT team keeps two lists of people: one in the directory and one in Okta. Someone must create each new hire twice, change each name twice, and disable each leaver twice. Sooner or later, someone forgets one step, and a former employee keeps access to a cloud app for weeks.

Integration makes the directory the source of truth, which means the one place everyone agrees is correct. A change made once in the directory flows to Okta, and from Okta to every connected app. This idea is part of what IT teams call the joiner, mover, leaver process: new people join, people move between teams, and people leave. Each event should update access automatically.

The whole design hangs on one small piece of software that sits inside your network.

Okta runs in the cloud, but your directory sits inside your company network, protected by firewalls. Opening the directory to the internet would be dangerous. So Okta uses an agent, a small program you install on a server inside your network. The agent reaches out to Okta, and Okta never reaches in.

flowchart LR
  U["User Browser"] --> O["Okta Cloud: Sign-In and Policies"]
  O --> UD[("Universal Directory")]
  O |"Outbound HTTPS only"| AG["Okta AD Agent on Windows Server"]
  AG --> DC1["Domain Controller 1"]
  AG --> DC2["Domain Controller 2"]
  O --> APPS["Connected Apps"]

Because the agent starts the connection, your firewall only needs to allow outbound web traffic from that one server. No one from the internet can send anything inward. This is one of the biggest reasons security teams accept this design.

The agent is small, but it carries the whole integration, so it is worth knowing well.

The Okta AD Agent is a lightweight Windows service. A service is a program that runs quietly in the background without anyone logged in. You install it on a Windows server that is joined to your domain. Many teams use a dedicated member server for this, rather than a domain controller, so that the agent does not compete with the server’s main job. Check Okta’s current guidance for the details that apply to your version.

What the agent does

Connection rules

The agent makes outbound web connections to Okta over HTTPS, which is the same secure channel your browser uses for banking. Inside your network, it talks to domain controllers using normal directory traffic such as DNS, Kerberos, and LDAP. Your network team should confirm that the agent server is allowed to reach both sides. If a proxy sits between the server and the internet, the agent can be set up to use it.

Service account

The agent uses a service account, a special directory identity made for software, not for people. For basic import and password checking, this account needs only read access to the OUs you import. You grant more rights only if you want Okta to reset passwords or unlock accounts. Fewer rights mean less damage if the account is ever misused.

Several Okta features have “directory” in their names. This chapter separates them so you pick the right one.

The most common mix-up is between the LDAP Agent and the LDAP Interface. They sound alike, but they point in opposite directions. The agent brings an existing directory into Okta. The interface lets older apps use Okta as if it were a directory. If you need one, you rarely need the other for the same goal.

This guide stays with the basic setup: the agent, import, and delegated authentication. The extras are valuable, but they are best added after the basic version is stable.

The exact screens change over time, but the order of the work stays the same.

Prerequisites worth checking early

• Time sync. Directory sign-in uses Kerberos, which fails when clocks drift too far apart, often by more than a few minutes.
• Name resolution. The agent server must resolve the domain’s DNS names correctly.
• A clean username plan. Decide how usernames will look before importing, because changing them later is painful.
• Admin approval. Get sign-off for the service account and its permissions in writing.

Import is how Okta learns who exists. It runs on a schedule and can also be started by hand.

An import is a pass where Okta asks the agent for the current list of users and groups in the chosen OUs, then compares that list with what Okta already knows. There are two kinds. A full import reads everything again, which is thorough but slower. An incremental import reads only what changed since the last run, which is fast and suits frequent schedules, such as hourly.

Matching: new person or existing person?

For every directory user, Okta must decide whether this is someone new or someone it already has. This step is called matching. Okta compares fields such as username or email using rules you set. An exact match links the directory user to the existing Okta user. A partial match may need a person to confirm it. If nothing matches, Okta creates a new user. Admins can choose to confirm exact matches automatically to save time.

flowchart TD
  A["Import starts"] --> B["Agent reads users and groups from chosen OUs"]
  B --> C{"Does an Okta user already match?"}
  C -- "Exact match" --> D["Link and update profile"]
  C -- "Partial match" --> E["Hold for admin review"]
  C -- "No match" --> F["Create new Okta user"]
  D --> G["Apply group memberships"]
  E --> G
  F --> G
  G --> H["Import complete and logged"]

Scheduling and scope

Choose a schedule that fits how fast your business needs changes to appear. An hourly incremental import is common for companies that hire often. Daily is fine for smaller, steadier teams. You can always run an import by hand when HR says a new executive starts in ten minutes. Limit the import to the OUs that truly hold employees, so service accounts, test users, and old junk do not arrive in Okta.

Every person has fields, such as name, email, and department. Mapping decides which side owns each one.

An attribute is one piece of information about a user, such as first name, department, or manager. The directory and Okta each have their own list of attributes, with slightly different names. Attribute mapping tells Okta which directory field feeds which Okta field. This is set in the Profile Editor, which is the Okta tool that shows and edits every user profile layout.

Mastering: who is the boss of this field?

When a person’s data comes from the directory, the directory is said to master their profile. That means a change made in the directory overwrites the same field in Okta at the next import. The fields tied to the directory become read-only in Okta, so admins cannot create a conflict by editing them in two places. If someone needs a name fixed, the fix goes into the directory.

Choosing the Okta username

The Okta username is how a person identifies themselves at sign-in, and it must be unique in your org. Many companies build it from the email address or the UPN. Others combine the short directory name with the company domain. Pick a format that is stable, because a person’s username is referenced by many apps, and renames can ripple across all of them.

This is the part users feel every day, and the part that makes the whole design clever.

With delegated authentication, Okta does not keep the user’s directory password. When someone types a password into the Okta sign-in page, Okta passes it through the secure channel to the agent. The agent asks a domain controller to verify it, and the answer, yes or no, goes back to Okta. The password stays under the directory’s control.

sequenceDiagram
  autonumber
  participant U as User
  participant O as Okta Cloud
  participant A as Okta AD Agent
  participant D as Domain Controller
  U->>O: Enter username and password
  O->>O: Find the user and check sign-in policy
  O->>A: Send the check request over the secure channel
  A->>D: Ask the directory to verify the password
  D-->>A: Valid or not valid
  A-->>O: Return the result
  O-->>U: Continue to next step or show an error

What stays the same for users

The directory’s own rules still apply. If the directory says a password must be changed every 90 days, or an account locks after several wrong tries, those rules still hold, because the directory is the one deciding. A wrong password typed in Okta counts as a failed attempt in the directory, so it can contribute to lockouts. Disabled or expired accounts cannot sign in, as the directory will say no.

Okta’s own checks still run on top

Delegated authentication only answers one question: is the password correct? Okta then applies its own sign-in policies, such as asking for a second factor like an app approval, blocking risky locations, or limiting access by device. The directory decides if the password is right, and Okta decides everything else about whether to let the user in.

A person’s record moves from the directory into Okta, onward to apps, and eventually out again.

Here is the typical life of a directory-sourced user. HR creates the person in the directory. The next import brings them into Okta. Group memberships decide which apps they receive. Later, if they change teams, the directory changes, the next import updates Okta, and app access updates with it. When they leave, the directory account is disabled, and the next import reflects that in Okta.

flowchart TD
  H["HR creates person in directory"] --> I["Next import brings the person into Okta"]
  I --> G["Group membership assigns apps"]
  G --> W["Person works and signs in with directory password"]
  W --> M{"Role or team changes?"}
  M -- "Yes" --> U["Directory updated then Okta updated at next import"]
  U --> G
  M -- "Person leaves" --> X["Directory account disabled"]
  X --> R["Okta reflects the change and access ends"]

Notice the last row. Moving a person to an OU that Okta does not import can look to Okta like they vanished. Plan your OU layout and your import scope together, so that routine directory housekeeping does not accidentally lock people out.

The timing also matters. Because Okta learns about changes at the next import, there is always a delay between a directory change and its effect in Okta. Hourly imports shrink this gap, and manual imports remove it for urgent cases. Password checks, however, always happen live at sign-in, so a disabled directory account fails the password check right away.

Groups are how a few directory changes turn into the right access for hundreds of people.

Along with users, Okta can import groups from the directory. An imported group appears in Okta with the same members. You can then assign apps to the group, and every member receives them. When someone joins the “Sales” group in the directory, the next import adds them to the group in Okta, and the sales apps appear for them without any extra work.

Good habits for groups

• Import only the groups you need. Thousands of old groups clutter Okta and slow reviews.
• Use clear names. A name like “App-Salesforce-Users” tells an auditor exactly what the group is for.
• Separate access groups from email lists. A group built for sending mail may have members who should not have app access.
• Use Okta group rules for extras. Rules can add people to Okta-only groups based on mapped fields, such as department, without touching the directory.

The agent sits between the cloud and your most sensitive internal system, so treat it with care.

The design already has good security habits built in. The connection runs outbound, travels over encrypted HTTPS, and does not require any open inbound port. Passwords are checked by your directory, not stored in Okta. Still, some risks remain, and most of them are about how you run the agent server.

Threats to keep in mind

Password spraying is an attack where someone tries one common password across many accounts, hoping a few users picked it. Okta policies, network zones, and multi-factor rules can slow this down before the directory gets flooded. Service account theft is another risk, which is why the account should be small, monitored, and protected with a long random password that is stored in a secure vault. A third risk is an old agent server that nobody patches because “it just works.” Put it on your regular maintenance list.

Finally, remember that time matters. Directory sign-in relies on correct clocks. A server with a drifting clock can cause strange, hard-to-find failures. Keep the agent server synced to the same time source as your domain controllers.

Servers fail. A good design makes sure that one failure is a small event, not an outage.

The simplest protection is to install more than one agent for the same domain, on separate servers. The agents work side by side, and Okta can use any healthy one. If one server is rebooted for patching, the others carry on. For larger companies, spread agents across different sites or network segments so that one local problem does not remove all of them.

Do not forget recovery planning for the human side. Write a short runbook that says who gets alerted, which server to check first, and how to confirm that sign-in is healthy again. A tired engineer at night will thank you for a one-page checklist.

A quiet integration is a healthy one, but only if you are watching the right signals.

Okta’s admin tools show the status of each directory integration and each agent, so you can see at a glance whether an agent is active. Beyond that, the System Log, which is Okta’s searchable activity record, shows sign-ins, import activity, and errors. Event names and wording can differ between releases, so search by user, by time, and by the word “agent” or “import” if a specific name does not match. One sign-in event type that often appears for directory users is named user.authentication.auth_via_AD_agent.

Useful alerts

• An agent has been disconnected longer than your tolerance.
• No successful import in the last expected window.
• A sudden drop in the number of active users, which may signal a bad scope change.
• A burst of failed directory password checks across many accounts.

On the server side, watch the agent’s Windows service status, disk space, and the event logs of the server. Also track the service account for lockouts. Combining Okta’s view with your own server monitoring catches problems that neither would show alone.

Every design choice has a price. Here is an honest look at both sides.

Choosing between related options

The main trade-off is control versus convenience. Keeping passwords in the directory gives you control and familiar rules, but it ties cloud sign-in to a server in your network. Moving fully to cloud-only users removes that dependency, but it is a bigger change that many companies do in stages. Basic integration is a popular first step because it adds the cloud benefits without changing how people think about their passwords.

Patterns are habits that work. Anti-patterns are habits that look fine until they hurt.

Patterns that work

Anti-patterns to avoid

These are the habits that separate a smooth integration from a stressful one.

Mistakes seen again and again

These stories are illustrative, built from common patterns, to show the ideas at work.

Most problems come from a short list of causes. Check these first.

When in doubt, follow the path of the problem. Start with the user’s Okta record, then the agent status, then the domain controller, and finally the network between them. Each hop has its own log, and the first place where the trail goes cold is usually the place where the problem lives.