Configure Okta Active Directory Imports with DirSync

Okta Active Directory imports using DirSync optimize communication with Active Directory (AD) and enable faster, more reliable incremental imports. Administrators can enable this feature in the Okta Admin Console after verifying agent readiness and permissions. Historically, incremental imports from AD are time-consuming and inefficient, often converting unexpectedly to full imports.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Directories
• Active Directory
• DirSync

Review the benefits of the DirSync feature.

Imports with AD using DirSync enable Okta to optimize communication with AD using the AD DirSync Control server extension recommended by Microsoft. This feature provides more efficient incremental imports, reduces the number of full imports required, and avoids conversion to full imports in most scenarios.

When a scheduled or manual incremental import is triggered, Okta imports only delta changes from AD for users, groups, and group memberships.

In General Access, this feature helps to:

• Optimize communication with AD by providing more efficient incremental imports and only bringing in updated attributes on users and groups.
• Reduce the need for full imports by eliminating domain controller (DC) affinity requirements for incremental imports.
• Eliminate manual and duplicative work by deactivating AD-sourced users in Okta when they are deleted or moved to an out-of-scope organizational unit (OU) in AD.

How is the DirSync feature enabled in Okta?

Verify the agent readiness in the Directory Integrations settings and enable the DirSync feature in the Provisioning tab.

1. Navigate to Directory Integrations, select the existing Active Directory instance, select the Agents tab, and click Check Now under DirSync Readiness Check to initiate the check.
    
2. Verify that the status displays Agents Ready for DirSync to confirm the agent version and permissions are correct.
   
3. Navigate to Provisioning > To Okta > General within the Active Directory instance, click Edit for General, and select the Enable imports with AD using DirSync checkbox to activate the feature.
    

NOTE: The first import after enabling this feature is a full import.

What are the frequently asked questions regarding DirSync?

What is the DirSync protocol?

Active Directory directory synchronization (DirSync) control is a Lightweight Directory Access Protocol (LDAP) server extension protocol that enables an application to search a directory partition for objects that have changed since a previous state. Read more about DirSync in the Microsoft documentation: Polling for Changes Using the DirSync Control.

Why does Okta require new permissions in Active Directory?

To run the DirSync control, an account requires DS-Replication-Get-Changes permission at the root of the partition being monitored. This enables the AD Agent service account to have visibility on all changes made to the objects, allowing Okta to handle scenarios like the movement of users across OUs, OU creation or deletion, and object deletions without requiring a full import. These permissions mirror the permissions Microsoft requires for running the DirSync protocol, as well as the permissions Azure AD Connect uses to run AD sync.

How did Okta's incremental imports function before DirSync?

Okta historically ran incremental imports based on the USN-Changed attribute in AD. This attribute increments serially when an object updates. This approach faced significant limitations due to a lack of visibility into out-of-scope objects and deleted objects, requiring a full import for these scenarios.

Review the known limitations of incremental imports using DirSync.

• Office 365 Universal Sync: This feature cannot function with Office 365 provisioning when a selected AD instance is used. If DirSync is active in the tenant, an AD instance cannot be chosen for Office 365 Universal Sync. Conversely, if the AD instance is already configured for Office 365 Universal Sync, DirSync cannot be enabled on the AD instance.
• Full import duration: Full imports may take longer with DirSync when importing a very small subset of objects or OUs from the AD domain. Full imports assess the entire AD domain for changes before sending specific objects to Okta.
• Initial import failure: The first import after enabling DirSync on the AD instance may fail with a permission error if the AD contains a large number of users and groups, causing the initial startup query to take longer than anticipated. Retry the import after a few minutes to resolve the issue.
• AD LDAP Filter: This feature cannot currently function alongside DirSync due to provisioning edge cases where users are missed from the import. Okta is addressing this priority and plans to release a fix soon.

Verify prerequisites before enabling DirSync.

• Agent Version: All active agents must run version 3.20.0 or later of the AD agent. If an agent that does not support DirSync picks up an incremental import, the import fails and triggers a full import. Remove all outdated disconnected agent records from the Agents list before running the first import with DirSync.
• User Deactivations: Deactivate AD-sourced users within AD first and let the AD import handle deactivation within Okta. If an administrator deactivates an AD-sourced user in Okta, the connection with AD is lost. Reactivating the user in Okta does not reconnect them to the AD object, requiring a full import to reconcile the directories.
• Permissions: The service account used by the AD agent requires specific permissions to run imports with DirSync. Without these permissions, the agent lacks visibility into the AD domain, and incremental imports fail to bring the latest data.