Configure Active Directory import and account settings

When you install the Okta AD agent 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 Directory (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 app-user user name is samAccountName and the Okta user profile user name (login field) is UPN, then Okta use UPN to sign the user in.

If your AD domain functional level is 2003, your AD user names must have a UPN that includes a domain.name format.

  1. In the Admin Console, go to Directory > Directory Integrations.
  2. Click Active Directory and then click the Provisioning tab.
  3. Click Integrations in the SETTINGS list and in the Import Settings area, complete these fields:
    • User OUs connected to Okta — Add or remove the Organizational Units (OUs) used to import users.
    • This is an Early Access feature. To enable it, contact Okta Support.

    • 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.

    • Group OUs connected to Okta  — Add or remove the OUs used to import groups.
    • 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.

      Info

      Caution

      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 Directory. For more information, see https://msdn.microsoft.com/en-us/library/cc223384.aspx.

  4. Click Save.

  5. Optional. In the Delegated Authentication section, select Enable delegated authentication to Active Directory if you want AD to authenticate your users when they sign in to Okta.
  6. Click Save.
  7. Click To Okta in the SETTINGS list, click Edit, and in the General area, complete these fields:
    • Schedule Import  — Select the frequency to import users from AD to Okta.

      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  — 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:
      • User Principal Name (UPN)  — Select this option to use the UPN from AD to create the Okta user name.
      • 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 mycompany.okta.com, then the Okta username is jdoe@mycompany.okta.com.
      • 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.

      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  — 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 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 scope of an AD OU or LDAP 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  — Select Universal Security Group Support to ignore domain boundaries when importing group memberships for your 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 Skip users during import 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.
    • 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 users from receiving activation emails before you are ready for them to begin enrolling in and using Okta.

  1. Click Save.

  2. In the User Creation & Matching section click Edit and 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.

    • 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.
    • 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 don't.
    • Confirm matched users  — Select Auto-confirm exact matches or Auto-confirm partial matches to automatically confirm exact or partial matches. If you don't select an option, matches are confirmed manually once the matching status is established and users are activated on the People page (Directory > People).
    • Confirm 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 don't select an option, new users are confirmed or activated manually on the People page (Directory > People).
  1. Click Save.

Next steps

Configure Active Directory provisioning settings