This is an Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. feature. To enable it, please contact Okta Support.
Configure the Okta Active Directory (AD) agent: new user interface
The instructions in this topic only apply if your orgThe Okta container that represents a real-world organization. has enabled the Early Access feature for the new AD ProvisioningProvisioning is the enterprise-wide configuration, deployment, and management of multiple types of IT system resources. Specifically, provisioning provides users access to equipment, software, or services. This involves creating, maintaining and deactivating required business process automation objects and attributes in systems, directories, and applications. user interface.
If you find the instructions in this topic do not match what you see in your user interface, refer to Install and configure the Okta Active Directory (AD) agent instead.
This topic walks you through the configuration options for the Okta AD agent. You can change these settings any time as you refine your Okta configuration.
You must have installed the Okta AD agent to perform these steps.
Procedure

After the AD agent is installed, you are taken to the Provisioning page for the AD appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. to make initial configuration choices. You can come back to the Provisioning page at any time to update your configuration choices by navigating to Directory > Directory Integration > Active Directory > Provisioning.
The Settings > Create User section gives Okta the ability to create users in AD. This allows you, for example, to import users from an HR system, create the users in Okta, and then have Okta create the users in AD. The HR system is the master, with Okta and AD being updated based on changes in the HR master. Or, another use case may include Okta being the source of truth for all user information and pushing those updates into AD.
To implement this functionality, you first need to create a group in Okta and then assign that group to your AD instance. When users are added to the group, they are also created in AD. A common scenario is to use group rules in this kind of flow to add users to the AD provisioning group automatically.
Allow Okta to create users in Active Directory — Used if Okta is the profile master or will be pushing user updates to AD from another app such as Workday.
To configure Okta to create users in AD:
- If you are not on the Settings page, navigate to Directory > Directory Integration > Active Directory > Settings.
- Scroll to the Provisioning Features > Create Users section.
- Click Enable.
- For Activation email recipient, enter the email address of the Okta adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. who should receive the activation email with the Okta end user's password. The admin is responsible for giving the end user their Okta password.
- Scroll to the bottom of the page and click Save.
Update User Attributes — If Okta is the master, changes to the Okta user profile are pushed down to AD.
Enable this to allow Okta to update user attributes in Active Directory when the app is assigned. Future attribute changes made to the Okta user profile automatically overwrite the corresponding attribute value in Active Directory.
This is an Early Access feature. To enable it, please contact Okta Support.
Update OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority.: Select this option to update an Okta-mastered user's OU when the group that provisions a user to AD changes. For details, see Enable Okta-mastered user Organizational Unit updates.
Note: If an Okta-mastered user's OU changes in AD, that change will not be reflected in Okta since Okta is the master for that user. The next time the user is updated in Okta, they will be provisioned back to the OU as set in Okta.
Warning:When Profile Push is enabled, Okta will update the CN attribute in AD. If there is a mapping defined for the cn property in the Profile Editor that mapping is applied. If there is no mapping or if the behavior for the CN mapping is set to Do not map then the CN is set to First Name + " " + Last Name.
Deactivate Users — Deactivate user accounts in AD if the user is unassigned or deactivated in Okta.
This setting is used when Okta is the source of truth for user profiles.
Enable this option to deactivate users' Active Directory account when they are unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.
Sync Password — Syncs users' AD password with their Okta password. (Optional)
Enable this option if you want each user's AD password to be synced to their Okta password. Any subsequent password changes users make in Okta are pushed to their user profile in AD. To enable the Sync Password option, Delegated AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect. must be disabled. For more information, see Using Sync Password.
When you have completed your selections, click Save.
The final section allows you map your AD attributes and set their values based on values stored in Okta. The attributes listed in the table are your AD attributes.
You can only add attributes to the directory profile if they are already in the directory, so Okta first does a schema discoveryAbility to import additional attributes to Okta step to populate the attribute picker. For Okta to discover the attribute, it must be added to an object within the User object hierarchy in the directory: user object, a parent object, or an auxiliary object.
The agent takes a few seconds to execute the schema discovery. When it’s done you’ll get a list of the attributes that Okta has the permissions to discover in the directory.
You will see a list of AD attributes that Okta has discovered and attempted to map to the default Okta user profile attributes. You can edit these mappings by clicking on the pencil icon.
Define your Okta Attribute Mappings For details, see Map profile attributess.

You can come back to the Provisioning > To Okta page at any time to update your configuration choices by navigating to Directory > Directory Integration > Active Directory > Provisioning.
This involves making decisions about:
- Import settings — To add users and groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups. from a designated Active Directory domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). into Okta. This includes whether to use Just-in-Time (JIT) provisioning to import users into Okta, how often to schedule imports from AD to Okta, and whether to send activation emails to new end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using apps to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control..
- During import Okta presents you with options for the username format. This value is used to associate the user in AD to Okta, therefore it's important to choose the correct value as this affects how your users sign in to Okta. By default Okta uses the Okta user profile username during delegated authentication. For example, if the AD app-user username is samAccountName and the Okta user profile username (login field) is UPN, then Okta will use UPN to log in the user.
- If you are on AD domain functional level of 2003, your AD usernames must in the domain name format. Users must have a UPN that contains a domain.name format.
- If you have activated the New Import and Provisioning Settings Experience for Active Directory in Early access, the Okta username format field uses the Okta expression language. If your org was created before October 4th (Preview) or October 9th, 2017 (Production), the Okta username format field uses a legacy expression language which is different than the Okta expression language. When your org moves to the new import and provisioning settings experience for AD, you do not need to update the custom expression in the Okta username format field unless you modify the custom expression. If you modify the custom expression in the Okta username format field, you need to use the Okta expression language or the expression will fail validation, and an error message will appear.
- Automatic matching of AD to Okta user accounts — To establish matching criteria (or rules) to specify how an imported user should be mapped to an existing Okta user. Clearly defining rules for matching helps to prevent multiple instances for the same user from being created.
User name format notes:
You can keep it consistent with device sign-in by standardizing on the format your users use to sign into their devices.

Important
Orgs created after October 4th (Preview) or October 9th, 2017 (Production) may see slightly different import and provisioning options described in Updated AD Profile Mapping options. These changes will be rolled out to orgs created before these dates at a later date, which will be announced in the Release Notes.
To configure import and account settings:
- If you are not on the Provisioning > To Okta page, navigate to Directory > Directory Integration > Active Directory > Provisioning > To Okta.
- In the General section, click Edit and make selections from the following options:
Schedule Import — Determine how often you want Okta to import users from AD.
Note: Following a successful import, under specific conditions Okta automatically sends an email to designated administrators. The email details the number of users and groups scanned, added, updated, or removed during the import. Okta only sends the email if the scan detects any new users or groups, or changes to any existing user profile or group membership.
Okta username format— Choose from one of the following options:
Important: It is critical that the username format selected here be the correct format when you first import users. Changing the value can cause errors for existing users.
- Email address — End users will sign in with their email addresses as their Okta username.
- SAM Account name — Okta combines the SAM Account Name with the AD domain to generate the Okta username. For example, if the SAM Account Name is jdoe and the AD domain is mycompany.okta.com, then the Okta username is jdoe@mycompany.okta.com.
- User Principal Name (UPN) — Use the UPN from AD.
- Custom — If you want to use a custom username to sign in to Okta, use the Custom option and the Okta Expression language to map the Okta username format. You can preview your changes to validate your mapping expression. Enter the name of a user to preview the mapping.
Screenshot
Note: All Okta users can sign in by entering the alias part of their user names as long as it maps to a single user in your organization. For example, jdoe@mycompany.okta.com could sign in using jdoe.
- JIT Provisioning — Just In Time (JIT) provisioning enables automatic user account creation in Okta the first time a user authenticates with AD Delegated Authentication, as well as updates to existing user profiles.
The security groups to which the user belongs are also imported if the group belongs to a selected OU. If a user signing in does not belong to a selected OU, the sign in fails. If you enable JIT, Delegated Authentication must also be enabled.This option can be used with or without scheduled imports. For details about JIT and AD domain scenarios, see FAQ: Okta and AD Groups.
Note: There are membership inconsistencies that can occur between “regular” imports and JIT provisioning. These membership anomalies may occur when using nested groups. During regular imports, a child group that is outside the scopeA scope is an indication by the client that it wants to access some resource. of an AD OU or LDAPLightweight Directory Access Protocol (LDAP) is a lightweight client-server protocol for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other connection oriented transfer services. object filter cannot be detected. If a parent group is within an OU/object filter scope but its child groups are not, the parent group membership is incorrectly resolved during import. JIT provisioning would correctly resolve these memberships to the parent group because its function only detects "flat" memberships.
- USG support — Enable this to ignore domain boundaries when importing group memberships for your end users. This assumes that the relevant domains are connected in Okta. You must also deploy an AD agent for every domain in your forest that contains the USG object that you want to sync with Okta. Each connected domain then imports its groups. When a user’s group memberships match any groups that were imported (from any connected domain in the forest), Okta syncs the memberships for the user to each group. Only groups from connected domains are imported. This setting requires JIT provisioning.
- Do not import users — Select this option to keep groups in sync without importing new users from your directory. Use it when you only want to create new users in Okta via JIT, not via imports, yet continue to use imports to sync groups..
Activation emails — Check this option to prevent Okta from sending activation email to new users. Admins can activate users. Activation emails can only be suppressed when a domain is using delegated authentication.
Tip: We recommend that you select not to send activation emails while you are doing the initial AD integration and configuration in your Preview environment. This prevents end users from receiving activation emails before you are ready for them to begin enrolling in and using Okta.
- Max Import Unassignment — Accept the default 20% or choose a custom percent. Halts any import which exceeds this number of app unassignments. This action prevents accidental loss of user accounts. This setting affects all apps with imports enabled. For details, see Import safeguard.
- Click Save.
- In the User Creation & Matching section, click Edit and make selections from the following options to select the conditions under which imported users will be identified as matching existing Okta users.
Matching rules are used in the import of users from all apps and directories that allow importing. If there is an existing Okta account, AD allows you to import and confirm users automatically. Establishing matching criteria (or rules) allows you to specify how an imported user should be mapped to an existing Okta user. Clearly defining rules for matching helps to prevent multiple instances for the same user from being created.
- Imported user is an exact match to an Okta user if:
- Okta username format matches
- Email matches
- The following combination of attributes match — Select from the list of options. Choose any combination from the list of options to establish your criteria. For the new imported user to be considered an exact match, each option that you select must be true.
- Allow partial matches — Partial matching means that the first and last name of an imported user matches that of an existing Okta user, but the user’s username or email address do not. Choosing this option legitimizes this scenario.
- Confirm matched users — Check to automatically confirm exact or partial matches. Leaving them unchecked requires that matches are confirmed manually; once the matching status is established. If manually confirmed, users are activated on the People page (Directory > People)
- Confirm new users — Check to specify that once the matching status indicating a new user is established, they are confirmed or activated automatically. Leaving them unchecked requires that new users are confirmed or activated manually on the People page (Directory > People).
- Click Save.
- Imported user is an exact match to an Okta user if:
- In the Profile & Lifecycle Mastering section:
- Click Edit.
- Allow Active Directory to master Okta users — Enable this option to allow AD to control the profiles of assigned users. User profiles will be read only in Okta. Profiles are managed based on Profile MasterA profile master is an application (usually a directory service such as Active Directory, or human capital management system such as Workday) that acts as a source of truth for user profile attributes. A user can only be mastered by a single application or directory at any one time. For more details, see the Profile Master page. When users are mastered by attribute, we call this attribute-level mastery (ALM). ALM delivers finer grain control over how profiles are mastered by allowing admins to specify different profile masters for individual attributes. Profile mastering only applies to Okta user profiles, not app user profiles. For more details, see Attribute Level Mastering. priority.
Select what should happen to the Okta user when the AD user is deactivated:
- Do Nothing:Prevents activity in the app from controlling the user life cycle. This still allows profile master control of attributes and mappings.
- Deactivate Okta user: This default setting allows the user to be automatically deactivated when deactivated in the target app.
- Suspend Okta user:This setting allows the user to be automatically suspended when deactivated in the target app.
- Select what should happen to the Okta user when the AD user is reactivated:
- Reactivate suspended users:Allows an admin to choose if a suspended Okta user should be reactivated when they have been reactivated in the app.
- Reactivate deactivated users:Allows an admin to choose if a deactivated Okta user should be reactivated when they have been reactivated in the app.
- Scroll the bottom of the page and click Save Settings.
- Click Save.
-
The final section allows you map your Okta attributes and set their values based on values stored in Active Directory. The attributes listed in the table are your Okta attributes.
You will see a list of AD attributes that Okta has discovered and attempted to map to the default Okta user profile attributes. You can edit these mappings by clicking on the pencil icon.
Define your Okta Attribute Mappings For details, see Map profile attributess.

To configure integration settings:
- If you are not on the Provisioning > To Okta page, navigate to Directory > Directory Integration > Active Directory > Provisioning > Integration.
- In the Import Settings section:
- User OUs connected to Okta — The agent can only access the OUs you select to import end users. If you need to modify the OU selection made during the agent install, make the changes here.
This is an Early Access feature. To enable it, please contact Okta Support.
Optional — Define user filters to perform granular imports from Active Directory. Create syntax queries to selectively import users matching the criteria that you specify.
Caution: Changing the default filter queries can result in deprovisioning users. To avoid unintended results, Okta strongly recommends that you test these filters in your directory environment to make sure that the results match your expectations.
Default queries:
- User filter – sAMAccountType=805306368
- Group filter – objectCategory=group
Back-linked attributes, such as memberOf are computed attributes and are not stored in your Active Directory database. As a result, changes to the user object are not visible to Okta and an import operation is not performed when changes occur. Okta recommends that you avoid the use computed attributes as mapped attributes, especially if you require changes in downstream systems as a result of attribute changes. The use of computed attributes as mapped attributes may lead to inconsistent data between your on-premises AD and Universal DirectoryUniversal Directory enables you to store an unlimited amount of users and attributes from applications and sources like AD or HR systems. Any type of attributes are supported including linked-objects, sensitive attributes, and pre-defines lists. All of it accessible by all apps in our OIN catalog, over LDAP or via API.. For more information, see https://msdn.microsoft.com/en-us/library/cc223384.aspx.
- Group OUs connected to Okta — The agent can only access the OUs you select to import groups. If you need to modify the OU selection made during the agent install, make the changes here.
This is an Early Access feature. To enable it, please contact Okta Support.
Optional — Define group filters to perform granular imports from Active Directory. Create syntax queries to selectively import users matching the criteria that you specify.
Caution: Changing the default filter queries can result in deprovisioning users. To avoid unintended results, Okta strongly recommends that you test these filters in your directory environment to make sure that the results match your expectations.
Default queries:
- User filter – sAMAccountType=805306368
- Group filter – objectCategory=group
Back-linked attributes, such as memberOf are computed attributes and are not stored in your Active Directory database. As a result, changes to the user object are not visible to Okta and an import operation is not performed when changes occur. Okta recommends that you avoid the use computed attributes as mapped attributes, especially if you require changes in downstream systems as a result of attribute changes. The use of computed attributes as mapped attributes may lead to inconsistent data between your on-premises AD and Universal Directory. For more information, see https://msdn.microsoft.com/en-us/library/cc223384.aspx.
- Click Save.
-
In the Delegated Authentication section:
- Enable delegated authentication if you want Active Directory to authenticate your users when they sign in to Okta. A user's Okta credentials are the same as their Active Directory credentials when delegated authentication is on.
- Click Save Settings.
What's next?
After you have installed the Okta AD agent and completed the basic configuration steps above, your next steps are to:
- Import Active Directory users and Confirm imported user assignments — Users imported from Active Directory are not activated until you confirm your import results. Once confirmed, you can send activation emails that direct your users to create their Okta account.
- Work with Active Directory user profiles and attributes — Customize the attribute mappings between AD and Okta.
- About Universal Directory and user profiles — Edit your Okta user profile.
- Optionally, depending on your environment:
- Install and configure the Okta IWA Web agent for Desktop SSO — Desktop SSO allows your users to be automatically signed into their Okta apps whenever they are signed into your Windows network. When users aren't on the Windows network they sign in through the normal Okta sign-in page.
- Configure Agentless Desktop SSO - new implementations
- Install and Configure the Active Directory Password Sync Agent