Before learning any settings, it helps to see how organizations collect directories, and why combining them is rarely as simple as merging them into one.

How the sprawl happens

• Acquisitions. A bought company arrives with its own directory, its own naming habits, and its own administrators. Merging directories can take years.
• Regional autonomy. A country office may run its own domain for legal, language, or control reasons.
• Security boundaries. Some organizations deliberately use separate forests to contain the damage of a breach, for example one forest for administrators and another for ordinary users.
• Legacy systems. An old application needs an old domain that nobody dares to retire.
• Partners and joint ventures. A shared project may have its own directory that neither side fully owns.
• History. A directory designed twenty years ago for a company that has since changed shape.

What the business wants

From the user’s side, none of this matters. A person wants to sign in once, reach their applications, and not be told that they belong to the wrong domain. From the security team’s side, the goal is a single, consistent set of rules: one place to enforce strong sign-in, one place to remove access when someone leaves, one place to see who has what. Okta sits in the middle as a single front door for many directories.

A handful of terms appear in every conversation about directories. Learning them once makes the rest of this guide easy.

The vocabulary

The two facts that matter most for Okta

First, names are only unique within a scope. A short sign-in name such as “jsmith” may exist in two different domains for two different people. A UPN is meant to be unique across a forest, but not across forests. So when you combine several directories, collisions are a real possibility, not a theoretical one.

Second, the permanent identifier is the object GUID, not the name. Names change when people marry, move teams, or are renamed during cleanups. The GUID stays. Good integrations key their links on stable identifiers, so a rename does not look like a brand-new person.

flowchart TD
    FA["Forest A"] --> DA1["Domain: corp.example"]
    FA --> DA2["Child domain: emea.corp.example"]
    FB["Forest B from an acquisition"] --> DB1["Domain: bluebird.example"]
    DA1 -.->|"Trust"| DB1
    DA1 --> UA["Users, groups, OUs"]
    DA2 --> UB["Users, groups, OUs"]
    DB1 --> UC["Users, groups, OUs"]
    

The picture shows a company that has grown by acquisition. Forest A has a parent domain and a regional child. Forest B is the acquired company’s own forest, linked to A by a trust. Each domain has its own users and groups. Okta must connect to all three domains to see all the people.

Okta lives in the cloud and your directories live inside your network. A small program called the agent links the two.

What the agent is

The Okta Active Directory agent is a small service installed on a Windows server that is a member of the domain it will serve. The agent opens an outbound, encrypted connection to Okta over the standard secure web port, and keeps it open. Because the connection is outbound only, you do not need to open inbound holes in your firewall to the directory. Okta sends requests down the connection, such as “import these users” or “check this password”, and the agent carries them out against a domain controller and returns the answer.

What the agent does

• Imports. Reads users and groups from the domain and sends them to Okta, on a schedule or on demand.
• Delegated authentication. Checks a person’s password against Active Directory when they sign in to Okta, so passwords stay in the directory.
• Provisioning back. Creates or updates users and groups in Active Directory when Okta is set up to write to it.
• Password operations. Handles password resets, changes, and expiry information according to your settings.
• Reporting. Sends status and health information so you can see in Okta whether it is working.

sequenceDiagram
    participant OK as Okta in the cloud
    participant AG as Okta AD agent
    participant DC as Domain controller
    AG->>OK: Open outbound secure connection and keep it alive
    OK->>AG: Request an import of users and groups
    AG->>DC: Query the directory
    DC-->>AG: Users and groups
    AG-->>OK: Send results
    OK->>AG: Check this user's password
    AG->>DC: Validate credentials
    DC-->>AG: Valid or not
    AG-->>OK: Result of the check
    

The sequence shows why no inbound firewall rule is needed. The agent dials out and Okta replies on the same connection. Passwords are checked in the domain controller, not copied to Okta, when delegated authentication is used. That keeps the directory as the single source of truth for credentials.

The first big design decision is how many Active Directory connections to create in Okta, and what each one covers.

The idea of an instance

In Okta, each connected directory appears as an Active Directory instance, a configuration object with its own agents, import settings, mappings, and username rules. An instance corresponds to a forest or domain that Okta can reach through its agents. Different directories that cannot be reached by the same agents, or that need different rules, become different instances. Exactly how Okta groups domains of one forest into an instance depends on the version and your setup, so confirm the current behavior in the documentation.

Common layouts

What belongs in the choice

• Network reach. An agent must be able to reach domain controllers for the directories it serves. Forests without network connectivity need their own agents.
• Ownership. Teams that own a domain often want control over its import scope and mappings.
• Rules. Different username formats, import filters, or password policies point to different instances.
• Scale. Very large directories may be better split for import speed and manageability.
• Future change. If a domain will be retired within a year, give it a separate instance so removal is easy.

flowchart LR
    OKT["Okta organization"] --> I1["AD instance: Forest A including child domains"]
    OKT --> I2["AD instance: Forest B acquired company"]
    OKT --> I3["AD instance: Partner forest"]
    I1 --> A1["Agents in Forest A"]
    I2 --> A2["Agents in Forest B"]
    I3 --> A3["Agents in the partner forest"]
    A1 --> D1["Domain controllers A"]
    A2 --> D2["Domain controllers B"]
    A3 --> D3["Domain controllers partner"]
    

The figure shows a clean pattern: one instance per forest, each with its own agents, and each agent talking only to the domain controllers of its own forest. The layout follows the real network and ownership boundaries, which makes troubleshooting much simpler.

One agent is a single point of failure. A good design uses several, placed with care.

Why more than one agent

If the only agent for a domain stops, Okta can no longer import users or check passwords for that domain, and people stop being able to sign in. Servers get patched, restarted, and sometimes fail. Running at least two agents per directory, on separate servers, means one can be down without anyone noticing. Okta spreads work across the agents that are connected and healthy.

Placement guidelines

• Separate servers. Do not put two agents on the same machine. A single server failure would take both down.
• Separate locations. Place agents in different sites or data centers where possible, so a site outage does not remove all agents.
• Close to domain controllers. Agents should be near healthy domain controllers for speed and reliability.
• Dedicated servers. Avoid sharing the agent server with unrelated heavy applications.
• Properly sized. Large estates and heavy sign-in loads need more capacity. Follow current Okta sizing guidance.
• Hardened. The server holds a service account with directory read power, so treat it as a sensitive system.

flowchart TD
    OKT["Okta"] --> AG1["Agent 1 in data center one"]
    OKT --> AG2["Agent 2 in data center two"]
    AG1 --> DC1["Domain controller in data center one"]
    AG1 -.->|"Fallback"| DC2["Domain controller in data center two"]
    AG2 --> DC2
    AG2 -.->|"Fallback"| DC1
    

The picture shows two layers of redundancy. If one agent or its server fails, the other keeps serving. If one domain controller fails, each agent can use another. Redundancy at only one layer is not enough.

Agent maintenance

Agents receive updates from Okta, and many installations update automatically. Plan for this: updates may restart the service briefly. With two or more agents, Okta can usually keep working during an update on one of them. Stagger server patching so that both agents are never restarted at the same time.

The agent acts with a directory account. How much power that account has is one of the most important security choices in the whole design.

What the account needs

The agent runs under a domain account that must be able to read the users and groups you want to import. If you also want Okta to create or update accounts, reset passwords, or manage groups in Active Directory, the account needs matching write permissions, but only for the parts of the directory involved. Directory permissions are normally granted through delegation on the relevant organizational units, so the account can touch only those units and nothing else.

Least-privilege rules

Protecting the account

• Strong, unique password. Stored securely, with a rotation plan.
• Restricted logon. The account should only sign in to the agent servers, not to workstations or other servers.
• Monitoring. Alerts on unusual use of the account.
• No interactive use. People should not sign in as the service account.
• Documented ownership. A named team owns the account, its password rotation, and its permissions.

flowchart LR
    AG["Agent service"] --> SA["Service account in the domain"]
    SA --> OU1["Delegated: read user OUs"]
    SA --> OU2["Delegated: reset passwords on user OUs"]
    SA -.->|"No rights"| ADM["Administrator groups and privileged accounts"]
    

The picture shows the aim: enough power to do the job, and none over the crown jewels. If an attacker took over the agent server, the damage would be limited to what the account is allowed to do. A domain administrator service account would hand the attacker the whole directory.

Importing is how Okta learns who exists. Choosing what to import, and how often, shapes everything that follows.

Choosing the scope

You do not have to import the whole directory. You choose which organizational units to include, and often can apply filters to select only certain users. A good scope includes the people who need access to cloud applications and excludes service accounts, test accounts, old disabled accounts, and administrative accounts that should never sign in through Okta. A narrow, deliberate scope is safer and faster than “import everything”.

Full and incremental imports

What happens on import

For each directory user, Okta decides whether to create a new Okta user, update an existing one, or take no action. It does this using matching rules, covered in a later chapter. Users who disappear from the scope, or become disabled in the directory, can trigger deactivation in Okta according to your settings. Because that action removes access, test it carefully before turning it on.

flowchart TD
    DIR["Directory user in scope"] --> MT{"Matching Okta user found?"}
    MT -- "No" --> CR["Create new Okta user"]
    MT -- "Yes, one match" --> UP["Link and update attributes"]
    MT -- "Yes, several matches" --> CF["Flag as conflict for review"]
    CR --> POL["Apply mappings and group rules"]
    UP --> POL
    

The picture shows three outcomes. New people are created, known people are linked and updated, and ambiguous cases are held back for a human decision. The ambiguous case matters most in multi-directory setups, where the same person may appear in several places.

Groups carry access decisions. In a multi-directory estate, group handling needs extra care to avoid name clashes and loops.

Two directions

Okta can import groups from Active Directory, so that existing directory groups become Okta groups that you can use to assign applications. It can also push groups from Okta to Active Directory, creating or updating directory groups whose membership follows Okta. Import suits organizations whose group structure already lives in the directory. Push suits organizations that want Okta to be the place where access is managed, with directory groups acting as a mirror for older applications.

Multi-directory pitfalls

• Name collisions. Two domains may each have a group called “Finance”. In Okta they must be distinguishable. Use naming conventions or prefixes that include the domain or forest.
• Loops. Importing a group from a directory and pushing the same group back can create confusing circular behavior. Decide the direction for each group and keep it.
• Nested groups. Active Directory allows groups inside groups. Okta’s handling of nested membership has limits, so check how your nested structures will be read.
• Cross-domain membership. Users from one domain can belong to groups in another within a forest or across trusts. Test these cases specifically.
• Large groups. Very large groups slow imports and pushes. Prefer smaller, purpose-built groups.
• Privileged groups. Never push or import membership of administrative groups through the integration, unless you have a specific, controlled reason.

flowchart LR
    GA["Forest A group: Finance"] -->|"Import with prefix"| OA["Okta group: A-Finance"]
    GB["Forest B group: Finance"] -->|"Import with prefix"| OB["Okta group: B-Finance"]
    OA --> APP["Application assignment"]
    OB --> APP
    OR["Okta rule group: All-Finance-Users"] -->|"Push"| GPUSH["Directory mirror group for legacy apps"]
    

The diagram shows how to avoid a typical clash. Each forest’s “Finance” group is imported with a prefix, so Okta holds two clearly different groups. A separate rule-based group, owned by Okta, is pushed to the directory when a legacy application still reads groups there.

When a person types a password, someone must check it. With Active Directory, that someone is usually the directory itself.

Delegated authentication

In delegated authentication, Okta does not keep the person’s password. When someone signs in, Okta passes the password through the secure agent connection to a domain controller of the correct domain, which says whether it is right. Okta then applies its own rules, such as extra factors, and creates a session. The password remains stored only in Active Directory. The advantage is that existing directory password rules, lockout policies, and expiry rules keep working. The cost is that Okta’s sign-in depends on the agent and domain controller being reachable.

Other approaches

Password change and reset

When a person changes or resets their password in Okta, the agent can write the new password to Active Directory, if the service account has the right to do so. Directory password rules, such as length and history, still apply, and failures are reported back to the person. In multi-directory setups, make sure each domain’s agent account has reset rights on its own users, and nothing beyond.

sequenceDiagram
    participant U as Person
    participant OK as Okta
    participant AG as Agent for the person's domain
    participant DC as Domain controller
    U->>OK: Username and password
    OK->>OK: Find the user and the directory they belong to
    OK->>AG: Check this password
    AG->>DC: Validate credentials
    DC-->>AG: Valid
    AG-->>OK: Valid
    OK->>U: Ask for additional factor if policy requires
    U->>OK: Approve
    OK-->>U: Session created
    

The sequence shows the routing step: Okta must know which directory to ask. In a multi-directory estate that depends on how users are linked to instances, which later chapters explain. The agent for that user’s domain does the checking, not agents of other domains.

People on office computers expect not to type a password at all. Desktop single sign-on can do that, but it needs care across many domains.

The idea of desktop single sign-on

When a computer is joined to a domain and a person is already signed in to Windows, their computer holds proof of that sign-in. Desktop single sign-on, using integrated Windows authentication, lets the browser present that proof to Okta, so the person is signed in without typing anything. It relies on a small web component installed in each domain, and on the browser being willing to send the proof to Okta’s address, which an administrator must allow through browser or group policy settings.

Complications with many domains

• One component per domain. Each domain or forest needs its own web component or equivalent, so that proofs from that domain can be checked.
• Routing. Okta must decide which component a browser should talk to. This usually depends on the network the person is on, or on the address range they come from.
• Trusts. Proofs from a domain only work if the checking component can validate them, which depends on trust relationships.
• Off-network users. People outside the office or on personal devices fall back to normal sign-in with password and factors.
• Browser settings. The browser must be configured to send proofs to the sign-in address, normally through central policy.

flowchart TD
    BR["Browser on a domain-joined computer"] --> RT{"Which network is the person on?"}
    RT -- "Forest A office network" --> WA["Desktop SSO component for Forest A"]
    RT -- "Forest B office network" --> WB["Desktop SSO component for Forest B"]
    RT -- "Outside any office" --> NORM["Normal sign-in: password and factors"]
    WA --> OKS["Okta session created"]
    WB --> OKS
    NORM --> OKS
    

The picture shows a sensible default: seamless where the person is on a known network, and ordinary sign-in everywhere else. Treat seamless sign-in as a convenience, not as the only path, because laptops travel and networks change.

What Okta calls a person, and how it recognizes them the next time, is the foundation of a multi-directory design.

Two different ideas

A username is what the person types or sees. An identity key is what the system uses to know it is the same person over time. They should not be the same thing. Usernames change when people marry, relocate, or get a new email format. The identity key must stay fixed. In Active Directory, the stable identifier is the object GUID, and Okta uses a directory identifier of this kind to remember which directory account belongs to which Okta user, so a rename in the directory is recognized as a rename, not a new person.

Choosing the Okta username

Why this matters more with many directories

In one domain, a username policy only has to be unique inside that domain. With several directories, the username in Okta must be unique across all of them. Two people named “Alex Kim”, one in each forest, might both have the short name “akim”. If both are imported with the same Okta username, the second import fails or collides. A username format that includes a unique element, such as a domain-specific suffix or an employee number, prevents this from the start.

flowchart LR
    A1["Forest A: akim"] --> F["Username format adds forest suffix"]
    B1["Forest B: akim"] --> F
    F --> U1["Okta username: akim at a-suffix"]
    F --> U2["Okta username: akim at b-suffix"]
    U1 --> OK1["Unique"]
    U2 --> OK2["Unique"]
    

The diagram shows the simplest protection: the suffix is part of the rule, so the two “akim” accounts become two different Okta usernames without any manual work. The suffix does not have to be shown to the person if the sign-in page lets them use their email or another friendly name.

Collisions are the most common surprise in multi-directory projects. Finding them early turns a crisis into a to-do list.

Where collisions appear

• Short sign-in names. The same sAMAccountName in two domains for two different people.
• User principal names. The same suffix and prefix used in two forests, often after an acquisition where both companies adopted a convention.
• Email addresses. The same address appears in two directories because of a shared mailbox or a migration in progress.
• Group names. Identical group names with different meanings.
• Employee numbers. Two HR systems issuing overlapping numbers.

A pre-import audit

Before connecting a second directory, export the identifying attributes from every directory and look for overlaps. A simple spreadsheet or script can count how many people share each short name, email, UPN, and employee number across directories. The result tells you how much work lies ahead and which username format to choose.

flowchart TD
    EX["Export identifying attributes from all directories"] --> CMP["Compare across directories"]
    CMP --> R1["Same person in several directories"]
    CMP --> R2["Different people sharing a name"]
    CMP --> R3["Data errors"]
    R1 --> A1["Plan matching and linking"]
    R2 --> A2["Choose unique username format"]
    R3 --> A3["Fix at source before import"]
    

The picture divides the overlaps by cause. Duplicate records of the same person need linking. Different people sharing a name need unique usernames. Plain mistakes need fixing at the source. Treating them all the same is how projects get tangled.

Mergers, secondments, and special-purpose forests mean many people have more than one directory account. Okta can recognize this, if you tell it how.

Matching and linking

When users are imported, Okta tries to match each directory account to an existing Okta user, using rules you define. A common rule is “same email address” or “same employee number”. When a match is found, Okta links the directory account to that Okta user rather than creating a new one. The result is one Okta person, with one profile, linked to accounts in several directories. When the person signs in, Okta can verify them against the directory account that holds their credentials, and applications see a single identity.

Choosing the matching rule

What to do about false matches

A wrong match is serious: two different people get merged into one profile, and one may gain the other’s access. For that reason, matching on a single weak attribute is risky. Prefer attributes that cannot be shared, test the rule on a sample first, and review the list of proposed matches before turning on automatic linking.

flowchart LR
    AA["Account in Forest A: sam.lee"] --> M{"Matching rule: employee number equal?"}
    BB["Account in Forest B: slee"] --> M
    M -- "Yes" --> ONE["One Okta user linked to both accounts"]
    M -- "No" --> TWO["Two separate Okta users"]
    ONE --> SIGN["Sign-in verified against the directory holding the credentials"]
    

The picture shows the payoff. The person has two directory accounts but one Okta identity, so a single deactivation in Okta, or a single policy, applies to both. The cost is that the matching rule is now a security decision: a wrong rule can merge strangers.

When one person’s data comes from several directories, you must decide which source supplies each attribute.

Mapping per instance

Each Active Directory instance has its own mapping that says which directory attribute fills which Okta attribute. Because directories differ, each mapping may differ too. One forest stores the department in one field and another stores it in a different field. One has titles in capital letters and another in normal case. Per-instance mappings let you translate each directory into the same standard shape in Okta.

Priority between sources

When two sources can set the same Okta attribute, one must win. Okta lets you rank the profile sources, and in many setups also choose the source of individual attributes. Without a ranking, the last import wins, and values can flip back and forth between runs. A good rule is to let the business system own business facts: HR owns title, department, and manager. Directories own technical facts: the directory name, the group membership, and the password state.

flowchart LR
    HR["HR source: title, department, manager"] --> UD["Okta profile"]
    DA["Forest A mapping: name, group membership"] --> UD
    DB["Forest B mapping: name, group membership"] --> UD
    UD --> PR{"Source priority per attribute"}
    PR --> OUT["One value for each attribute"]
    

The picture reminds us that the Okta profile is the middle ground. Each source translates into the standard shape, and priority picks one value per attribute. A short table of attribute owners keeps everyone on the same page.

People start, change, and leave. In a multi-directory estate, each event must reach every account the person holds.

Joiners

A new hire normally appears first in HR, then in a directory when IT creates the account. Okta imports the account, matches or creates the Okta user, applies mappings and group rules, and assigns applications. Decide which directory a new person belongs to, and write that rule down. A person hired into the acquired company should land in that company’s directory until a planned migration moves them.

Movers

A person who moves department keeps the same accounts, and rule-based groups change automatically. A person who moves to the other company, or to a different forest, is harder. Their old account may be disabled, and a new account created in the other forest. Unless the two are linked by a stable key, Okta sees a leaver and a joiner. Plan these moves so the Okta user continues, with the new directory account linked and the old one retired.

Leavers

When someone leaves, every account must be dealt with. If an Okta user is linked to several directory accounts, deactivating the Okta user removes access to applications, but the directory accounts may remain enabled for other uses. The leaver process should therefore also disable the directory accounts, by the directory team or through Okta’s write-back where configured.

stateDiagram-v2
    [*] --> Active: Linked to directory accounts
    Active --> Suspended: Leave of absence
    Suspended --> Active: Return
    Active --> Deactivated: Termination recorded in HR
    Deactivated --> DirectoriesDisabled: All linked directory accounts disabled
    DirectoriesDisabled --> [*]
    

The state picture shows that Okta deactivation is only one step. A complete leaver process also reaches the directories, because directory accounts can be used for other things, such as signing in to old applications that do not use Okta at all.

The most common reason for multiple directories is a purchase. The goal is one front door quickly, long before the directories are merged.

The scenario

Imagine a fictional company, Northwind Foods, with 4,000 employees in a forest called the corporate forest. It acquires Bluebird Kitchens, with 600 employees in a separate forest. A trust exists between the two for file sharing, and some people at Bluebird already have accounts in both forests. Northwind uses Okta for its applications and wants Bluebird staff to use the same applications within weeks, while the long process of merging directories takes a year.

The approach

flowchart LR
    CF["Corporate forest: 4000 users"] --> I1["Instance: Corp"]
    BF["Bluebird forest: 600 users"] --> I2["Instance: Bluebird"]
    I1 --> OKU["Okta users with standard profile"]
    I2 --> OKU
    HR1["Northwind HR"] --> OKU
    HR2["Bluebird HR"] --> OKU
    OKU --> APPS["Shared applications"]
    

What the team learned

The first audit found 37 people with accounts in both forests, 11 pairs of different people sharing a short name, and a group named “Finance” in both. Matching on employee number linked 33 of the 37 dual-account people correctly. The remaining four had typing errors in one HR system, which were corrected at source. The colliding short names were solved by the username format. The groups were imported with prefixes. The pilot revealed that Bluebird’s password policy was stricter than Northwind’s, so Bluebird staff kept their existing rules because delegated authentication used each person’s own directory. A year later, when the directories were merged, the stable identity keys let the team move accounts without creating duplicates in Okta.

A single forest with regional child domains is simpler than several forests, but it has its own traps.

The scenario

Consider a fictional manufacturer, Ironvale Components, with one forest and a parent domain for the head office plus child domains for Europe, Asia, and the Americas. Each region has its own IT team and its own organizational units. About 9,000 people are spread across the four domains. Trusts between the domains inside a forest are automatic, and a global catalog holds a partial index of every object in the forest.

Design questions

• One instance or several? A single instance for the forest is simpler. Separate instances give each region independent settings and fault isolation.
• Where do agents live? At least two per region, close to the regional domain controllers, so sign-ins do not cross slow links.
• Who owns the import scope? Each region may choose its own OUs, but a central team should approve to keep rules consistent.
• How are usernames made unique? Short names are unique only within a domain, so use UPNs or a custom format that includes the region.
• Cross-domain groups. Users from one region may belong to groups in another. Test these cases.
• Moves between regions. A person transferring between child domains is effectively a new account, so plan for linking.

flowchart TD
    FOR["Ironvale forest"] --> HQ["Parent domain: head office"]
    FOR --> EU["Child domain: Europe"]
    FOR --> AS["Child domain: Asia"]
    FOR --> AM["Child domain: Americas"]
    EU --> AGEU["Two agents near Europe domain controllers"]
    AS --> AGAS["Two agents near Asia domain controllers"]
    AM --> AGAM["Two agents near Americas domain controllers"]
    HQ --> AGHQ["Two agents at head office"]
    AGEU --> OKT["Okta"]
    AGAS --> OKT
    AGAM --> OKT
    AGHQ --> OKT
    

The picture shows the key principle: put the agents near the people they serve. A password check from Tokyo to a domain controller in Frankfurt works but is slow and fragile. Local agents keep sign-in fast and keep a regional outage from affecting others.

Some security-minded designs split people from resources. This shapes where Okta looks for accounts, and where it does not.

The pattern

In an account forest and resource forest design, user accounts live in one forest, and servers and applications live in another. The resource forest trusts the account forest, so users from the first can be granted access in the second. The idea is that a breach of the resource side does not reveal user credentials, since those live elsewhere. Another variation is an administrative forest, holding only privileged accounts for managing the other forests, with strict controls.

Impact on Okta

• Connect the account forest. People are in the account forest, so that is where Okta needs to import and check passwords.
• The resource forest may need little. If it holds only servers and application groups, Okta may need it only for group push, if at all.
• Groups across trusts. Access in the resource forest is often controlled by groups there, with account forest users as members. Decide whether Okta pushes or reads those groups.
• Administrative forests stay out. Privileged accounts should not be imported into Okta or managed by its agent unless there is a strong reason.
• Trust direction matters. Know which forest trusts which, since it affects which accounts can be recognized where.

flowchart LR
    ACC["Account forest: employee accounts"] --> OKT["Okta"]
    RES["Resource forest: servers and application groups"] -.->|"Trusts account forest"| ACC
    OKT -->|"Group push for legacy apps"| RES
    ADM["Administrative forest: privileged accounts"] -.->|"Excluded from Okta"| OKT
    

The picture shows a clean separation. Okta handles ordinary users, and leaves privileged administration to its own protected forest. Mixing the two would weaken the very separation that the design was built to create.

Not every directory sits comfortably inside your network. Some belong to partners, some have no trust, and some cannot be reached directly at all.

When the agent cannot easily reach the directory

A partner’s forest might sit behind their own firewall, with no network path to your agent servers. Placing your agent inside their network would give your organization’s software a foothold in theirs, which they may not accept. There are several alternatives, each with trade-offs.

Choosing

The best answer is usually the one that leaves each party responsible for its own people. Federation lets the partner’s directory stay theirs: their staff sign in with their own credentials, and Okta trusts the assertion. Your organization controls what those people may access, and the partner controls whether they still work for them. Where federation is impossible, accounts managed in Okta with an end date and a named sponsor are a workable fallback.

sequenceDiagram
    participant P as Partner employee
    participant PI as Partner identity provider
    participant OK as Okta
    participant APP as Shared application
    P->>OK: Open application sign-in page
    OK->>PI: Redirect for authentication
    PI->>PI: Verify the person in the partner directory
    PI-->>OK: Signed assertion
    OK->>OK: Apply access policy for partner users
    OK-->>APP: Grant session with limited access
    

The sequence shows that federation avoids touching the partner’s directory at all. The partner’s own offboarding process closes access automatically, because their provider stops vouching for the person. This is why federation is usually preferable to copying partner accounts into your systems.

Many multi-directory estates are temporary. Planning for the day directories merge keeps the Okta side calm.

What consolidation means

Consolidating directories means moving accounts from one domain or forest to another, often using a migration tool, and then retiring the old one. During the move, accounts are copied or moved, passwords may be carried across, and the old identifiers may be kept in a special attribute so permissions continue to work. For Okta, the key problem is that a moved account has a new permanent identifier, which can make it look like a brand-new person.

Keeping the Okta identity

• Link on a business key. Match moved accounts to existing Okta users using an employee number or another stable business attribute, not just the name.
• Plan the order. Add the new directory instance, link accounts, test sign-in against the new account, then retire the old instance.
• Avoid duplicate users. Run imports from the new directory with matching rules enabled before the old account is removed.
• Keep usernames stable. Where possible, preserve the Okta username so applications do not see a change.
• Handle password transitions. Decide whether people keep their password or reset at the move.
• Retire cleanly. Disable accounts and import scopes in the old directory, then remove its instance after a quiet period.

flowchart LR
    OLD["Old forest account, id one"] -->|"Migration tool moves account"| NEW["New forest account, id two"]
    OKU["Okta user, linked to id one"] --> RM["Match on employee number"]
    NEW --> RM
    RM --> RL["Okta user relinked to id two, same Okta identity"]
    

The picture shows the aim: one Okta identity that outlives the move. Applications never see a new person, tokens and assignments carry on, and the only change is the directory account behind the scenes.

Most integration problems turn out to be plumbing. A few network basics prevent most of them.

What the agent needs

• Outbound access to Okta. The agent must reach Okta’s addresses over the secure web port. Allow the addresses Okta documents, and use names rather than fixed numbers where the documentation allows, since Okta’s addresses change.
• Access to domain controllers. Agents must reach domain controllers using the standard directory ports. Ports vary by feature, so use Okta’s current list.
• Working DNS. The agent server must resolve the domain’s names, including the records that identify domain controllers by site.
• Accurate time. The directory’s authentication depends on clocks agreeing within a small tolerance. Servers must use a reliable time source.
• Proxy awareness. If the network forces traffic through a web proxy, the agent must be configured to use it, and the proxy must not break the secure connection.
• Site awareness. The directory’s sites and subnets let agents find nearby domain controllers. Keep them accurate.

flowchart TD
    AG["Agent server"] --> DNS["DNS: resolve domain and domain controller names"]
    AG --> TIME["Time source: stay in sync"]
    AG --> DCP["Directory ports to domain controllers"]
    AG --> PRX["Proxy or firewall: outbound secure connection"]
    PRX --> OKT["Okta"]
    

The checklist in the picture explains a surprising share of support cases. When something breaks, start by asking whether DNS resolves, the clock is right, the ports are open, and the outbound path works. Only then look at settings in Okta.

The integration connects your cloud sign-in system to the heart of your Windows estate. That makes it a target and a risk worth managing.

The main risks

• Compromised agent server. An attacker on the server can use the agent’s account and see credentials passing through for delegated authentication.
• Over-privileged service account. Power beyond what the integration needs expands the damage.
• Pivoting across forests. A foothold in one forest used to reach another through trust or a shared account.
• Account takeover by write-back. If Okta can reset passwords in the directory, an attacker with Okta administrator rights might reset a directory user’s password.
• Mismatched accounts. A wrong matching rule that merges two people.
• Privileged accounts in scope. Administrators imported into Okta, or reachable through group push.
• Stale accounts. Disabled people still enabled in a forgotten directory.

flowchart TD
    ATT["Attacker foothold"] --> T1["Agent server"]
    ATT --> T2["Okta administrator account"]
    ATT --> T3["Weak matching rule"]
    T1 --> C1["Dedicated hardened server, narrow service account"]
    T2 --> C2["Strong sign-in, change approval, alerts"]
    T3 --> C3["Strong match keys, sample testing, review"]
    

The picture reminds us that the integration crosses a boundary between cloud and directory. Both sides need protection: the servers that hold the agent, and the administrators who control the settings. A weakness in either undermines the other.

An integration you cannot see is one you cannot trust. A few signals and a calm routine cover most needs.

What to watch

Okta’s admin console shows agent status for each instance, and its System Log records imports, authentication events, and configuration changes. Send these to your central monitoring system. On the Windows side, the agent writes to the server’s event logs, and the domain controllers record authentication events. Combining both views makes it much easier to find where something went wrong.

Alerts worth having

• Fewer than two agents connected for any instance.
• An agent not heard from for more than a few minutes.
• An import that fails, runs much longer than usual, or deactivates an unusually high number of users.
• A spike in failed delegated authentication.
• Any change to an instance, mapping, or matching rule.
• Service account lockouts.

flowchart TD
    P["Problem reported"] --> Q1{"One user or many?"}
    Q1 -- "One" --> U1["Check the account in the directory and the user in Okta"]
    Q1 -- "Many in one domain" --> U2["Check agents, domain controllers, and network for that domain"]
    Q1 -- "Many across domains" --> U3["Check recent Okta changes and the Okta service status"]
    U2 --> U4["Check import and sign-in logs"]
    U3 --> U4
    

Directories with tens or hundreds of thousands of people need planning. Most scale problems come from imports, groups, and sign-in bursts.

Where load comes from

• Large initial imports. The first import of a big directory can take hours. Schedule it for a quiet time.
• Large groups. Groups with thousands of members slow imports and pushes.
• Frequent full imports. Running full imports every few minutes wastes effort, and incremental imports are lighter.
• Sign-in peaks. Morning surges put load on agents and domain controllers at once.
• Chatty attribute reads. Importing many unneeded attributes adds time and traffic.
• Product limits. Okta sets limits on directory objects, agents per instance, and operation rates, which vary by license and change over time.

flowchart LR
    SIGN["Morning sign-in peak"] --> AG1["Agent 1"]
    SIGN --> AG2["Agent 2"]
    SIGN --> AG3["Agent 3"]
    AG1 --> DCA["Domain controller A"]
    AG2 --> DCB["Domain controller B"]
    AG3 --> DCB
    

The picture shows the simplest way to scale sign-in: add agents and make sure the domain controllers behind them can cope. The directory side is often the real limit, so check controller load as well as agent count.

Small changes to a directory integration can lock out thousands of people. Treat each one with the care of a production release.

Risky changes

• Changing import scope, such as adding or removing OUs.
• Changing the username format or matching rules.
• Changing profile mappings or attribute priority.
• Turning on deactivation, write-back, or group push.
• Adding, removing, or upgrading agents.
• Changing the service account or its permissions.
• Retiring an instance.

A safe change routine

The test user set

flowchart LR
    CH["Planned change"] --> TS["Test directory and test org"]
    TS --> PV["Import preview in production"]
    PV --> PL["Pilot group"]
    PL --> RO["Full rollout"]
    RO --> MN["Monitor and keep rollback ready"]
    

A handful of failures cause most outages. Know them, and practice the fixes.

A recovery routine

flowchart TD
    OUT["Sign-in failures reported"] --> A{"Only one domain?"}
    A -- "Yes" --> B{"Agents connected?"}
    B -- "No" --> C["Restore agents and network path"]
    B -- "Yes" --> D["Check domain controllers and service account"]
    A -- "No, all domains" --> E{"Recent change in Okta?"}
    E -- "Yes" --> F["Revert the change"]
    E -- "No" --> G["Check Okta service status and shared network"]
    

These patterns have proved themselves in many organizations. Adapt them to your own estate.

flowchart TD
    DIRS["Many directories"] --> INST["One instance per boundary, two agents each"]
    INST --> ID["Unique usernames and stable identity keys"]
    ID --> MATCH["Matching on business keys links dual accounts"]
    MATCH --> PROF["One Okta profile, sources ranked per attribute"]
    PROF --> POL["Policies and applications see one identity"]
    PART["Partners"] -->|"Federation"| POL
    

These habits look convenient and create lasting trouble. Recognize them early.

Every choice gives something up. Naming the trade-offs makes decisions deliberate, and a short checklist keeps good habits alive.

The main trade-offs

Best practices

• Draw the whole directory estate before connecting anything, including trusts and owners.
• Audit overlaps in names, emails, UPNs, and employee numbers across all directories.
• Decide the Okta username format and matching rules before the first large import.
• Install at least two agents per instance on separate servers, near healthy domain controllers.
• Use narrowly delegated service accounts, one per domain, and exclude privileged accounts.
• Import only needed OUs and attributes, and rank sources per attribute.
• Keep group names distinct with prefixes, and decide import or push direction for each group.
• Start with lifecycle actions off, preview imports, pilot, then roll out.
• Monitor agents, imports, sign-in failures, and configuration changes.
• Reconcile HR status with enabled accounts in every directory.
• Test break-glass access on a schedule.

Common mistakes

• Assuming short sign-in names are unique across domains.
• Patching both agent servers at the same time.
• Letting two sources write the same attribute with equal priority.
• Turning on deactivation before verifying the import scope.
• Forgetting that a moved account has a new directory identifier.
• Ignoring time synchronization and DNS.
• Creating directory trusts to solve application-level needs.

quadrantChart
    title Choosing the integration shape
    x-axis Same team and rules --> Different teams and rules
    y-axis Directories well connected --> Directories isolated
    quadrant-1 Federate or separate instance with local agents
    quadrant-2 Separate instances with local agents
    quadrant-3 One instance, shared rules
    quadrant-4 Separate instances, central standards
    Child domains one team: [0.2, 0.2]
    Regional domains own admins: [0.7, 0.25]
    Acquired company forest: [0.75, 0.6]
    Partner forest: [0.9, 0.9]
    

The picture is a way of thinking, not a measurement. Directories run by one team and well connected can share an instance. Directories run by different teams with different rules deserve their own instances. Isolated or partner directories suggest federation or local agents with careful agreements.

To pull everything together, here is an invented company and a complete multi-directory design. The company, numbers, and names are made up for teaching.

The company

Skybridge Energy is a fictional utility with 7,500 employees. It has a corporate forest with three domains: head office, Europe, and the Americas. It acquired a smaller engineering firm, Ridgeline Engineering, with 900 people in a separate forest. A third, small forest holds an operational technology network for power plants, with 150 accounts and strict separation. A consulting partner supplies about 80 contractors who work on projects. The company wants one sign-in for all cloud applications within a quarter.

The design

flowchart LR
    CF1["Corporate: head office domain"] --> I1["Instance HQ"]
    CF2["Corporate: Europe domain"] --> I2["Instance Europe"]
    CF3["Corporate: Americas domain"] --> I3["Instance Americas"]
    RF["Ridgeline forest"] --> I4["Instance Ridgeline"]
    I1 --> OKU["Okta profile: one identity per person"]
    I2 --> OKU
    I3 --> OKU
    I4 --> OKU
    HR["HR system"] --> OKU
    PIDP["Partner identity provider"] -->|"Federation"| OKU
    OT["OT forest"] -.->|"Not connected"| OKU
    

How the first six months went

The audit before connecting Ridgeline found 22 people with accounts in both forests, 14 pairs of different people sharing a short name, and a group called “Engineers” in both. Matching on employee number linked all 22 dual-account people, after two typing errors were fixed in the HR system. The username format with a company element handled the short-name collisions without anyone noticing, and groups were imported with prefixes.

During the pilot, a test found that Ridgeline’s agents were using a domain controller in a distant site because of a missing subnet entry. Correcting the site configuration cut sign-in time by more than half. In month two, a patching window restarted both agents in the Europe domain at the same time, and sign-ins failed for six minutes. The team staggered patching afterward and added an alert for fewer than two connected agents. In month four, a scope change that moved an OU caused an import to propose deactivating 400 users. The cap on deactivation per run held the import, and the team corrected the scope before any account was affected.

The quarterly reconciliation of HR status against enabled accounts in all four directories found 31 leavers still enabled in the Ridgeline forest. They were disabled the same day, and the leaver process was extended to include all linked directories.

Short answers to questions that come up often. Agent versions, features, limits, and menu names change over time, so confirm exact details in the current Okta documentation.

Connecting many Active Directory domains and forests to Okta is mostly a matter of clear boundaries, stable identities, and careful change.