Install and configure the Okta AD agent

If this is your first Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management. (AD) integration, you should review the topics in Get started. You should also remove duplicate entries and correct formatting issues. Correcting issues before you begin speeds the integration and import processes.

The AD user profile schema requires both the first and last name. You can create an Okta mastered user without a first or last name, but you cannot import an AD user into Okta without a first and last name.

If you're installing the Okta AD agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations. on a DMZ server, you must open specific ports. See Configure DMZ server ports for Active Directory integrations

Install the Active Directory agent on the host server

Download and install the latest version of the Okta AD agent on your host server(s) to make sure that you have the most current features and functionality and get optimum performance. If you are running multiple Okta AD agents, make sure they are all the same version. Running different versions within a 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). can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.

To download the agent from another computer, copy the AD Agent installer to the host server.

  1. On the host server, sign in to Okta with your 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. account that has a minimum role of Super Admin and click Admin to access the Okta Admin Console.
  2. Click Directory > Directory Integrations.
    1. Click Add Directory and then select Add Active Directory.
    2. Review the installation requirements and click Set Up Active Directory
    3. Click Download Agent.
  3. On the host server, locate the downloaded file and double-click the file to launch the installer.
    1. Click Yes at the message Do you want to allow the following program to make changes to this computer?.
    2. Choose an installation destination. Click Next.
    3. Select the AD domain you want to manage with this agent. Click Next.
    4. Select a domain user for the Okta AD agent to run as and click Next:
      • Select Create or use the Okta Service account (recommended) and complete the prompt to set a password. Okta recommends using a complex password for security.
      • Select Use an alternate account that I specify if you want to assign the Okta AD Agent to run as an existing domain user.
    5. Optional — If appropriate for your environment, specify a proxy server through which your AD agent will connect. Click Next.
      Note: If you are installing an AD agent version 3.4.11 or later, in environments where internet traffic is required to go through a proxy, the sign-in flow for the AD agent installer uses the proxy settings specified within the installer. If no proxy settings are specified, the machine defaults are used.
    6. To register the AD Agent with the Okta service, enter your Okta subdomain name. This is the <mycompany> part of the example: <mycompany> Click Next.
    7. On the Okta Sign In page, enter your admin username and password, and then click Sign in.
    8. The Okta AD agent requires several permissions. Click Allow Access. The agent installation completes.

      Note: If the error message displays The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel, see Troubleshooting.

    9. Click Finish.
  4. When the Okta AD agent starts, return to the browser and click Next. On the following screens you will select some basic configuration options. You can change these and other settings at a later time.
    1. (First time installations for this domain only) At the Connect an Organization Unit to Okta screen, select the OUs from which you want to import 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..
    2. Select the Okta Username format that you want AD-imported end usersEnd users are people in your org without administrative control. They can authenticate into apps from the icons on their My Applications home page, but they are provisioned, deprovisioned, assigned, and managed by admins. to use when logging in to Okta and then click Next.
      Choose from:
      • Email address
      • SAM Account Name
      • User Principal Name (UPN)

      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.

    3. On the Import AD Users and Group dialog, click Next.

    Note: To reconfigure 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. and import settings, as well as other settings, return to the Settings tab (Directory > Directory Integrations > Active Directory > Settings). For details, see Configure import and account settings.

  5. On the Build User Profile tab, select the attributes that you want to use to build your Okta user profiles. You can modify these attributes at a later time if you want to accept the defaults at this time. Click Next.

    To learn more about how Okta uses profiles and attributes, see About Universal Directory and user profiles and Work with Active Directory user profiles and attributes

  6. Click Done.

Your AD domain is now integrated with Okta. Continue toConfigure import and account settings

If you enabled the 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 for the new AD import and provisioning user interface, see Configure the Okta Active Directory (AD) agent: new user interface

Configure import and account settings

After the AD agent is installed, you are taken to the Settings 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 Settings page at any time to update your configuration choices by navigating to Directory > Directory Integrations > Active Directory > Settings.

This involves making decisions about:

  1. On the Okta Admin Console click Directory > Directory Integrations > Active Directory > Settings.
  2. Scroll to 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..
    1. Enable delegated authentication if you want AD to authenticate your users when they sign in to Okta. A user's Okta credentials are the same as their AD credentials when delegated authentication is on.

      InstanceAn instance, or computer instance, is a virtual machine (VM) or individual physical computer, used to host a software appliance.-level Del Auth is optimized for use in environments with multiple AD instances. It allows admins to delegate authentication on a per AD-instance level to support more granular authentication scenarios such as the following:

      • Configure Okta to be the authentication master for users in some AD instances.
      • Configure AD to be the authentication master for users in the remaining AD instances (meaning users sign-in using their Windows credentials).
      • Continue to rely on Okta to provision to all AD instances

    2. Click Save Settings.
  3. Scroll to the Import and Provisioning > Import and Account Settings section and make selections from the following options:
    1. 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.
    2. 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.
    3. This is an Early Access feature. To enable it, contact Okta Support.

      User/Group Filter — 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 filtersAMAccountType=805306368
      • Group filterobjectCategory=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

    4. 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 Active Directory integration FAQ.

      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. 

    5. Schedule Import  — Determine how often you want Okta to import users from AD.

      Select Do not import new users to leverage scheduled imports to keep user profiles and 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.

      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.

    6. Note: Orgs created after October 19th (Preview) or October 25th, 2017 (Production) may see different import and provisioning options in the user interface elements described below. These changes will be rolled out to orgs created before these dates at a later date, which will be announced in the Release Notes. For details about the import and provisioning changes, see AD Updated Profile Mapping options.
      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, then the Okta username is
      • SAM Account name + Configurable Suffix  — When using this option, do not include the @ character before the Configurable Domain.
      • 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.ClosedScreenshot

      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, could sign in using jdoe.

    7. Activation emails  — Check this option to prevent Okta from sending activation email to new users. Admins can activate users.

      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.

    8. 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.
    9. Max Import Unassignment  — Accept the default 20% or choose a custom per cent. 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.
  4. In the Match Settings section, 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. Active Directory, OPP, and all provisioning-enabled apps support automatic importation and confirmation of users into Okta.  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.

    Note: This feature does not apply to CSV-imported user lists.

    1. Imported user is an exact match to an Okta user if:
      • Okta username format matches
      • Email matches
      • The following 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.

    2. 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.
  5. In the Confirmation Settings section, select the automatic confirmation option that matches the policies of your organization. If you do not select an auto-match option, all user imports must be confirmed manually.
    • 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).

    • New users  — Check these boxes to specify that once the matching status signifying 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).
  6. Scroll to the bottom of the page and click Save Settings.

Configure provisioning settings