Install and Configure the Okta Active Directory Agent
Okta Active Directory (AD) integration allows you to integrate Okta with your on-premise AD. AD integration provides delegated authentication support (allowing users to sign in to Okta with their AD credentials), user provisioning and de-provisioning, and the ability to import users and AD groups.
To enable AD integration, you must install the Okta AD agent. Before installing the agent, you must create a special administrative user whose password is Okta-specific and not tied to AD. Once you integrate AD, you are able to specify how to handle an Okta account when the source account is deactivated or reactivated. For details see Profile & Lifecycle Mastering.
AD integrations in a newly-created organization automatically have the following default settings enabled:
Okta recommends that no administrators be AD mastered.
Note: This does not affect existing administrators you have created who are AD mastered. We encourage you to disconnect your admins from AD (select Directory > People > More Actions > Disconnect from AD, select the admin users who you want to disconnect, and then click the appropriate Disconnect button).
Mandatory account permissions
You must have permissions for the following accounts:
Creating an Okta Administrative User Account
You must create an administrator account before you begin installing the AD Agent. This user should have an Okta-specific password and not an AD password. The AD Agent connects to Okta using this account.
User Permissions Required to Install the AD Agent (Version 3.4.x)
During installation, you are asked if you want to let the installer create the Okta service account. To do so, you must have the following permissions:
With either option, the installer grants logon as a service to the domain user you select.
Okta Service Account Options
The AD agent runs under the account you specified (either the Okta service account the installer created or the domain user you selected). Depending on the configuration of your integration, the agent performs the following actions:
Minimum Agent Service Account permissions)
Before adjusting the permissions on your directory make sure you understand how Active Directory permissions are set and plan how to manage this within your environment.
By default the AD Agent installer will allow you to create a new service account if you do not choose an existing account. The newly created OktaService user has the permissions of the Domain Users group. OktaService is also considered to be a member of Authenticated Users and Everyone special identity groups when the agent is running.
The Okta AD Agent Management Utility also includes the option of adding the OktaService account to the Domain Admins group. If you require functionality listed below but don't want to make your service account a full admin, make sure the following permissions are set.
Update User Attributes
Reset Password, Forgot Password , and Sync Password
Activate and Deactivate User
You can add the permissions listed here using the commands below. Save them to a batch file and change the target OU and service account info to be correct for your environment. Remember to remove permissions you do not need and add any attributes you have mapped for provisioning within Okta. You can get the complete list of user attributes from your Directory user profile on https://<org>/admin/universaldirectory.
Additional Reference information
You may find these additional references helpful in setting permissions:
Important: To ensure that you have up-to-date functionality and get optimum performance from your Okta AD agent(s), we strongly recommend that you download and install the latest version of the agent on your designated host server(s). If you are running multiple Okta AD agents, make sure that all of them are the same version. Running different versions within a domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.
In addition, you must open your DCOM RPC ports. In addition to TCP 135, Microsoft RPC (MS-RPC) uses randomly generated ports from TCP 49152-65535 for Vista/2008 and above. These ports are also known as "random RPC ports." RPC clients use the RPC Endpoint Mapper (EPM) which runs on TCP135 to tell them which dynamic ports were assigned to the server.
For detailed information on configuring your ports on a DMZ server, see the Microsoft Support page. For more information on the required network ports, refer to Service overview and network port requirements for Windows. For more information on random RPC ports, refer to How to configure RPC dynamic port allocation to work with firewalls
Uninstalling and Reinstalling the AD Agent
Important: To ensure that you have up-to-date functionality and get optimum performance from your Okta AD agent(s), we strongly recommend that you download and install the latest version of the agent on your designated domain server(s). If you are running multiple Okta AD agents, make sure that all of them are the same version. Running different versions within a domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.
When you uninstall and reinstall your AD agent, you must decide whether you also want to remove the old Okta API token from your system. If you are performing an upgrade, you are not required to remove the old token. To remove the API token, you must delete the Okta AD Agent folder and deactivate and remove your old AD agent.
Note: To avoid down time if you intend to continue using an AD agent, you must have at least two agents running before you uninstall one of them. For more information, see Configuring High Availability by Installing Multiple Active Directory Agents.
Uninstalling the AD Agent
Reinstalling the AD Agent
Installing the AD agent does not overwrite the configuration data in the Okta AD Agent folder. If you want to reinstall and create a new API token, make sure you delete the Okta AD Agent folder (as described above) before you reinstall the AD agent. Then perform the following steps to reinstall your AD agent and deactivate and remove the old AD agent in Okta:
If you are performing an upgrade or reinstall and you do not want to revoke the Okta API token of the old AD agent, you are finished. Otherwise, proceed to the next step.
Upgrading in place
It is possible to upgrade the agent without having to uninstall it. The agent installer will automatically upgrade an existing agent.
Delegated authentication (Del Auth) makes your users' Okta credentials the same as their AD credentials. Enable it if you want Active Directory (AD) to authenticate your users when they sign into Okta.
Instance-Level Del Auth moves Del Auth enablement from the org-level (Security > Delegated Authentication) to the instance-level (Directory > Directory Integrations). While preserving current Del Auth functionality, instance-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:
When Instance-Level Del Auth is enabled, you can configure it in Directory > Directory Integrations > Active Directory > Settings. Your former org-level delegated authentication settings are preserved but no longer managed from Security > Delegated Authentication > Active Directory.
Options in this section allow you to configure import and provisioning settings, as well as make changes to your initial configuration.
IMPORT AND ACCOUNT SETTINGS
Select Directory > Directory Integrations > Active Directory and then select the Settings tab.
Separate OU selectors
Separate OU selectors for Users and Groups allows you to separately specify the OUs from which to import users, and from which to import groups. This also allows you to ignore the OUs that contain users or groups that you don't want in Okta.
To select all OUs, select the top folder. Or you can select individual OUs.
Note: If you are running a pre-3.3.5 version of the agent, changes to Group OU settings will not take effect for JIT Provisioning until you restart your agents. To avoid the need to restart agents each time you change this setting, upgrade all of your AD agents to version 3.3.5 or later.
This is an Early Access feature. To enable it, please contact Okta Support.
Using filters allows you 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.
For more about importing groups, see these related topics:
Just in-Time Provisioning (JIT)
Select Create and update users on login to create and update users at sign on. This option can be used with or without scheduled imports.
Okta JIT allows for the automatic creation of new user accounts at sign on, 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.
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.
JIT and AD Domains
For details about JIT and AD domain scenarios, see FAQ: Okta and AD Groups.
Delegated Auth and Desktop SSO
There are other forms of JIT that integrate with AD. Namely, delegated authentication for Windows environments, and Desktop SSO for imports that can be verified on the Imports page. For details, see Delegated Authentication.
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 and group memberships.
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
Note: Orgs created after October 4th (Preview) or October 9th, 2017 (Production) may see slightly 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.
Specify a username format. When you import users from AD, Okta uses this attribute to generate the Okta username. If you select 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 firstname.lastname@example.org. When using the "SAM Account Name + Configurable Suffix" option, do not include the @ character before the Configurable Domain.
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, email@example.com could sign in using jdoe.
You can optionally select Don't send new user activation emails for this domain to prevent Okta from sending an activation email to new users.
Select the Universal Security Group (USG) option if you want 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.
If there is an existing Okta account, AD allows you to import and confirm users automatically. Select the automatic confirmation option that matches the policies of your organization:
Note: This feature does not apply to CSV-imported user lists.
Matching rules are used in the import of users from all apps and directories that allow importing. Establishing matching criteria allows you to specify how an imported user should be defined as a new user or mapped to an existing Okta user.
Imported user is an exact match to Okta user if: the match criteria that establishes whether an imported user exactly matches an existing Okta user. 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. Note that if you choose the third option, the first and second choices are disabled.
Allow partial matches: Partial matching occurs when the first and last name of an imported user matches that of an existing Okta user, but the user’s username or/and email address do not.
Confirm matched users: Select to automate the confirmation or activation of existing users. Unchecked, matches are confirmed manually.
Confirm new users: Select to automate the confirmation or activation of a newly imported user. If this option is selected, you can uncheck it during import confirmation. Note that this feature does not apply for users who already exist in Okta.
Note: Orgs created after October 19th (Preview) or October 25th, 2017 (Production) may see slightly 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.
Checking the Enable box creates or links a user in Active Directory.
Update User Attributes
Okta updates a user's 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. For details, see Enable Okta-mastered user OU changes.
This is an Early Access feature. To enable it, please contact Okta Support.
Update OU: Select this option to update an Okta-mastered user's OU when the group that provisions a user to AD changes.
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 update in Okta, they will be provisioned back to the OU as set in Okta.
Deactivates 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.
Enabled by default, profile mastering makes Active Directory the identity authority for connected users. When enabled, user profiles are not editable in Okta and all changes are synced to Okta during provisioning events. AD defaults as a profile master, but you can disable this option to have AD treated as a normal application.
If you disable AD as the profile master, user updates performed in AD are not pushed back to the user in Okta. For example, if you change a user's name in AD, the name change is not pushed to the Okta user account. In addition, you cannot reset a user's AD password in Okta because their credentials are still being managed by AD. You can, however, enable the Sync Password option to push passwords to Active Directory and disable Delegated Authentication. Your users will have their delegated Okta password, but any subsequent password updates are pushed to AD.
This is an Early Access feature. To enable it, please contact Okta Support.
This section allows you to determine what happens when a user is deactivated in an app: should they be deactivated, suspended or remain an active user is Okta?
When a user is deactivated in the app
When a user is reactivated in the app
Only the highest priority profile master for an Okta user can deactivate or suspend an Okta user. To verify the highest priority profile master, review the Profile Masters page.
Enable this option if you want each user's AD password to be synced to their Okta password. Any subsequent password changes users make are pushed to their user profile in AD. To enable the Sync Password option, Delegated Authentication must be disabled. For more information, see Using Sync Password.
Profile Attributes & Mappings
For information about profile attributes and mappings, see Using Custom Attributes with Active Directory.
Registering Multiple Domains From One AD Agent
Okta AD integration support also allows you to set up multiple domains from one AD agent, reducing the number of servers or virtual machines you need to connect to multiple domains. After you install the AD agent, you can use the Okta AD Agent Management Utility to add more domains.
To configure high availability, you can install additional AD agents on separate servers or virtual machines. We recommend setting up two or more AD agents per domain.
Note: Installing multiple agents in close geographical proximity to your users does not enhance performance. When you have multiple agents installed, the process randomly selects which agent it uses so user location is not a factor. In addition, setting up large numbers of agents in this manner can cause problems when the system attempts to perform status checks on their performance.
Setting up a second AD agent follows the same steps as setting up your first agent. If you created the Okta service account with the first AD agent, then you are prompted to enter your password during the second agent installation.
To install additional AD agents on a domain:
AD Agent Request Handling
Each agent connects to the Okta service independently. When the service needs to communicate to AD (for example, to authenticate a user), it picks one of the available agents and sends it a task to complete. If one of the agents becomes unavailable, it is automatically removed from the queue and not given additional tasks.
Agents send periodic messages to the service. If the service does not receive a message for 120 seconds, it is marked as unavailable.
Domain Controller Selection
The AD agent relies on the underlying operating system to select which domain controller to communicate with.
Changing the AD Agent User
Configuring the Number of Threads the AD Agent Uses
You can configure the number of threads the AD agent uses to poll the server for tasks. If you are running the AD agent on a large-scale server, you can increase the thread count as an alternative to using multiple AD agents.
For example, to create three instances, do the following:
Now the agent has four concurrent polling threads searching for actions to perform.
Note: There is a 10 thread limitation for this feature.
Error when resetting a Windows password
If the following error displays when your end users try to reset their Windows password in Okta,
New Windows password: Unexpected error when changing password, please try again
. . . and the following description was written to Reports > System Log at the same time,
. . . then you are probably not enforcing Active Directory's Password History policy. To enforce the policy, make sure that your Okta AD Agent is version 3.4.1 or later and your Domain Controllers are running Windows Server 2008 R2 or later.
Error when installing the agent
During agent installation, if the error message displays,
The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel
. . . then you are probably attempting to install a version of the AD agent in which SSL pinning is enabled by default and your environment is one in which the agent's support for SSL certificate pinning prevents communication with the Okta server. This is most likely to occur in environments that rely on SSL proxies. To allow installation to complete in this case, Okta recommends that you bypass SSL proxy processing by adding the domain okta.com to a whitelist.
Alternatively, if SSL certificate pinning is enabled you can choose to disable it as described below.
To disable SSL certificate pinning if it is enabled
To re-enable support for SSL certificate pinning if it is disabled