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.

Configure the Okta Active Directory (AD) agent: new user interface

You use 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. agent to integrate Okta with your 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) instance. If you have enabled New 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. Settings Experience for Active Directory on the Features page, the information provided here will help you configure the Okta AD agent.

The Provisioning page is where you manage your configuration settings. To view the Provisioning page, click Directory > Directory Integration > Active Directory > Provisioning. You can change these settings any time as the needs of your orgThe Okta container that represents a real-world organization. change.

Prerequisites

Configure provisioning and user settings

Use the settings on the Provisioning to 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. page to define how user profiles are created and updated, deactivate user's AD accounts, synchronize passwords, and map attributes.

Allow Okta to create users in Active Directory

Enabling Create Users lets Okta create users in AD. You enable this functionality when Okta is the 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. or you want to push user updates to AD from applications such as Workday. To implement this functionality, you first 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. Group rules are often used to automatically add users to the AD provisioning group.

  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 the Provisioning tab.
  3. Click To App in the SETTINGS list.
  4. Click Edit.
  5. In the  Create Users section, click Enable.
  6. In the Activation email recipient field, enter the email address of the Okta admin who receives activation emails with the Okta end user's password. The admin is responsible for giving the end user their Okta password.
  7. Scroll down and click Save.

Enable Update User Attributes

When Update User Attribute is enabled and Okta is the profile master, changes to the Okta user profile are pushed to AD. Enabling this setting allows Okta to update user attributes in AD when an application is assigned. Future attribute changes made to the Okta user profile automatically overwrite the corresponding attribute value in AD.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To App in the SETTINGS list.
  4. Click Edit.
  5. In the Update User Attributes section, click Enable.
  6. Click Ok in the Enable User Updates dialog box.
  7. Scroll down and click Save.

Enable Update OU

This is an Early Access feature. To enable it, contact Okta Support.

Enable 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. to update an Okta-mastered user's Organizational Unit (OU) when the group that provisions a user to AD changes. For more information, 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.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To App in the SETTINGS list.
  4. Click Edit.
  5. In the Update OU section, click Enable.
  6. Scroll down and click Save.

Enable Deactivate Users

Enable Deactivate Users to deactivate a user's AD account when their account is unassigned or deactivated in Okta. This setting is used when Okta is the source of truth for user profiles. Accounts can be reactivated if the app is reassigned to a user in Okta.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To App in the SETTINGS list.
  4. Click Edit.
  5. In the Deactivate Users section, click Enable.
  6. Scroll down and click Save.

Enable Sync Password

Enable Sync Password to synchronize a user's AD password with their Okta password. Any password changes users make in Okta are pushed to their AD user profile. To enable Sync Password, delegated authentication must be disabled. For more information, see Using Sync Password.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click Integration in the SETTINGS list.
  4. Scroll down and clear the Enable delegated authentication to Active Directory check box.
  5. Click Save.
  6. Click To App in the SETTINGS list.
  7. Click Edit.
  8. In the Sync Password section, click Enable.
  9. Click Save.

Map attributes

The Attribute Mappings section lets you map your AD attributes to Okta attributes. 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 does a schema discoveryAbility to import additional attributes to Okta to populate the list of available attributes. 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.

Schema discovery takes a few seconds to complete and when it’s done you’ll get a list of the attributes that Okta has the permissions to discover in the directory and attempted to map to the default Okta user profile attributes. For more information, see Map profile attributes.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To App in the SETTINGS list.
  4. To edit existing mappings or map attributes, scroll down to Attribute Mappings and click Go to Profile Editor.
  5. Click Mappings.
  6. Click Save Mappings.

Configure import and account settings

Import and account settings define how 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 an 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). are imported into Okta. This includes import methodology, import frequency, and whether activation emails are sent to new users.

Here are some things to consider when creating usernames:

  • During user import, you define the username format. This format determines the association between AD to Okta users. 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.

You can keep it consistent with device sign-in by standardizing the format your users use to sign into their devices.

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

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.

Configure general settings

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To Okta in the SETTINGS list.
  4. Click Edit in the General section.
  5. Select an option for Schedule Import. 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. Select an option for Okta username format:

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

  1. Select JIT Provisioning  to enable automatic user account creation in Okta the first time a user authenticates with AD 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., 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.

  1. Select USG 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.
  2. Select Do not import users to keep groups in sync without importing new users from your directory. Use it when you only want to create new users in Okta using JIT, not through imports, yet continue to use imports to sync groups.
  3. Select Activation emails 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.
  4. Click Edit next to Max Import Unassignment to 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 safeguards.
  5. Click Save.

Configure user creation and matching settings

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.

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To Okta in the SETTINGS list.
  4. Click Edit in the User Creation & Matching section.
  5. Select an option for Imported user is an exact match to an Okta user if:
  • Okta username format matches
  • Email matches
  • The following attribute matches
  • The following combination of attributes matches — Select an option from the list. For the new imported user to be considered an exact match, each option that you select must be true.
  1. Select an option for Allow partial matches:
  • Partial match on first and last name — 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.
  1. Select an option for Confirm matched users:
  • Auto-confirm exact matches — 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).
  1. Select an option for Confirm new users:
  • Auto-confirm new users — Select this option 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).
  • Auto-activate new users
  1. Click Save.

Configure profile and lifecycle mastering

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To Okta in the SETTINGS list.
  4. Click Edit in the Profile & Lifecycle Mastering section.
  5. To allow AD to control the profiles of assigned users, select Allow Active Directory to master Okta users.
  6. Select an option for When a user is deactivated in the app:
  • 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.
  1. Select an option for When a user is reactivated in the app:
  • 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.
  1. Click Save.

Map attributes

The Attribute Mappings section lets you map your Okta attributes and set their values based on values stored in AD. 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.

For more information, see Map profile attributes

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click To Okta in the SETTINGS list.
  4. To edit existing mappings or map attributes, scroll down to Attribute Mappings and click Go to Profile Editor.
  5. Click Mappings.
  6. Click Save Mappings.

Configure integration settings

  1. On the Okta Admin Console, click Directory > Directory Integrations.
  2. Click Active Directory and the Provisioning tab.
  3. Click Integration in the SETTINGS list.
  4. In the Import Settings section:
    1. User OUs connected to Okta  — The agent can only access the Organizational Units (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. This is an Early Access feature. To enable it, 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 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 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 https://msdn.microsoft.com/en-us/library/cc223384.aspx.

    3. 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.
    4. This is an Early Access feature. To enable it, 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 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 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.

  5. Click Save.
  6. In the Delegated Authentication section, select Enable delegated authentication to Active Directory to use your AD instance to authenticate users signing in to Okta. A user's Okta and Active Directory credentials are the same a when delegated authentication is enabled.

  7. Click Save.

What's next?

After you have installed and configured the Okta AD agent, you'll want to complete these tasks:

Your environment might require the completion of these optional tasks:

Top