Configure Active Directory import and account settings

When you install 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. or the needs of your business change, you define how and when user data is imported. Defining the user name format is a critical part of this process. The user name is used to associate the user in 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) to Okta. It's important to choose the correct user name format as this affects how your users sign in to Okta. By default Okta uses the Okta user profile user name during delegated authentication. For example, if 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.-user user name is samAccountName and the Okta user profile user name (login field) is UPN, then Okta use UPN to log in the user.

If your AD 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). functional level is 2003, your AD user names must have a UPN that includes a format.

  1. On 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. Console, click Directory > Directory Integrations.
  2. Click Active Directory and then click the Settings tab.
  3. Optional. In the 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. section, select Enable delegated authentication to Active Directory if you want AD to authenticate your users when they sign in to Okta.
  4. In the Import and 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. section, complete these fields:
    1. User OUs connected to Okta — Add or remove the Organizational Units (OUs) used to import users.
    2. 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, contact Okta Support.

    3. User Filter — Create a syntax query to selectively import users matching the criteria that you specify. The default is sAMAccountType=805306368.

    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.

    1. Group OUs connected to Okta  — Add or remove the OUs used to import 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. This is an Early Access feature. To enable it, contact Okta Support.

      Group Filter — Create a syntax query to selectively import groups matching the criteria that you specify. The default is objectCategory=group.

      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.



      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 of 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 Active Directory instance 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

    3. JIT Provisioning  — Select Create and update users on login to automatically create Okta user accounts the first time a user authenticates with AD Delegated Authentication, or their existing user profile is updated.

      The security groups to which the user belongs are also imported if the group belongs to a selected 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.. 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. 

    4. Schedule Import  — Select the frequency to import users from AD to Okta.

      Select Do not import users to keep user profiles and groups synchronized without importing new users from your directory. Use this option when you want to use import functionality to synchronize groups, but want to create new Okta users using Just In Time (JIT) provisioning.

      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.

    5. Okta username format  — The username format you select must match the format you used when you first imported users. Changing the value can cause errors for existing users. Choose one of the following options:
      • Custom  — Select this option to use a custom user name to sign in to Okta. Enter the Okta expression language to define the Okta user name format. To validate your mapping expression, enter a user name and click the view icon.
      • Email address  — Select this option to use an email address for the Okta user name.
      • SAM Account name  — Select this option to combine the SAM Account Name and 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  — Select this option to combine the SAM Account Name and a configurable suffix to create the Okta user name. When using this option, do not include the @ character before the Configurable Domain.
      • User Principal Name (UPN)  — Select this option to use the UPN from AD to create the Okta user name.

      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.

    6. Activation emails  — Select this option to prevent Okta from sending an activation email to new users. Admins can activate users.

      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 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. from receiving activation emails before you are ready for them to begin enrolling in and using Okta.

    7. USG support  — Select Universal Security Group Support 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.
    8. Max Import Unassignment  — Click edit to modify the value that the number of app unassignments stops. The default is 20%. This action prevents accidental loss of user accounts. This setting affects all apps with imports enabled. See Import safeguards.
  5. 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:  — Choose one of the following options:
      • Okta username format matches
      • Email matches
      • The following required attributes match  — Select 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.
      • The following attributes match  — Select 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  — Select this option to allow a match when the first and last name of an imported user match an existing Okta user, but the user’s username or email address do not.
  6. In the Confirmation Settings section, choose one of the following options:
    • Matched users  — Select Auto-confirm exact matches or Auto-confirm partial matches to automatically confirm exact or partial matches. If you do not select an option, matches are confirmed manually once the matching status is established and users are activated on the People page (Directory > People).

    • New users  — Select Auto-confirm new users or Auto-activate new users to automatically confirm or activate new users when the matching criteria is met. If you do not select an option, new users are confirmed or activated manually on the People page (Directory > People).
  7. Scroll down and click Save Settings.

Next steps