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 usersIn Okta literature, we generally refer to "users" as the people who serve as Okta administrators. When we refer to "end users" we are generally referring to the people who the administrators serve. That is, those who use Okta chiclets to access their apps, but have no administrative control. to sign in to Okta with their AD credentials), user provisioning and de-provisioning, and the ability to import users and AD 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..
To enable AD integration, you must 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.. 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, users that you deactivate in AD are also deactivated in Okta and the assignment is broken. If you later reactivate that user, the user is re-imported into the initial unassigned state.
AD integrations in a newly-created organization automatically have the following default settings enabled:
- Delegated authentication
- Just-in-Time (JIT) provisioning
- The import schedule set to never
- Profile mastering
- 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.
- Install on Windows Server 2008 or Later — You need access to a Windows server to install the Okta AD Agent. You do not need to install the agent on the domain controller itself. Your system must have 20Mb memory for the AD Service Account that is created upon agent installation.
Note: You must be running IE 10 or later on your Windows Server.
- .NET 4.0 (minimum) up to .NET 4.6.x (downloaded and installed automatically with the agent if no suitable version is found on the target machine at runtime).
- Installing the agent on a DMZ server — You must open several ports.
- AD password history enforcement — To enforce the AD Password History policy, you must use Okta AD Agent version 3.4.1 or later and your Domain Controllers must be running Windows Server 2008 R2 or later.
- 256 Mb of free memory for the service to run.
- Service Dedicated AD Service Account with Domain user permissions
- Separate server for domain controller (can be shared).
- Must be a member server within your active directory forest — We recommend the host server be a member in the same active directory domain of which your Active Directory users are members but is not required. The member server can be in a different domain, but must be in the same forest. Placing the agent on a different domain may cause performance issues.
- Consider the agent a part of your IT infrastructure – The host server where the agent resides must be on at all times. Do not install it on your laptop. The host server must have a continuous connection to the Internet so that it can communicate with Okta.
- Run this setup wizard from the host server – We recommend running this setup wizard in a web browser on the host server where you want to install the agent. Otherwise, you must transfer the agent installer to the host server, and then run the installer
- Creating 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. users – If you are using the Okta AD integration functionality, you should always have an Okta administrator whose password is Okta-specific and not tied to AD.
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).
- If you are using a third-party delegated authentication service, such as that of Salesforce.com which delegates authentication into one service and to another service (like AD via Okta), then you should always have a Salesforce.com admin account that is not assigned to a delegation authentication-enabled profile. For example, you should configure a Salesforce.com admin user whose password is specific to Salesforce.com, not Active Directory.
You must have permissions for the following accounts:
- Okta administrative user.
- An Active Directory (AD) user account to run the AD Agent Installer.
- Okta service account (created by the installer) – A service account under which the AD agent process runs after installation. This account can be created automatically by the installer, or you can select an existing account.
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.
- From the Administrative Dashboard, select Directory > People, and then click Add Person to create a user (for example, ADAgent@mycompany.com).
- Select Security > Administrators, and then click Add Administrator.
- Select the type of administrator. We recommend that you configure an organization or application administrator. For details about administrator roles, see Administrators.
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:
- Be a member of the domain admins group. This is required because you must be able to create a new AD user in AD that will act as the AD agent service account.
- Have local administrator privileges. If you are installing the AD agent but using an existing user account to run as the service account, you only need local administrator privileges.
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:
- Read users, OUs, and groups — Requires read access on the accessed objects. By default, a domain user has sufficient permission to do this. We recommend read access on the entire domain, but it is not required.
- Authenticate users — No special permissions are required.
- Change user passwords (by supplying the current password) — No special permissions are required.
- Set user passwords (administratively, without the current password) — Requires permissions to set passwords for users.
- Create and update users, attributes, and memberships in AD with values pushed from Okta — Requires permissions to read and write to the attribute(s) you are updating.
- Create, delete, and manage user accounts — For create and update user flows.
- Reset user passwords and force password change at next logon — For syncing passwords.
- Read all user information — For import and create user flows.
- Modify the membership of a group — For Group Push.
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.
- Select Directory > Directory Integrations.
- Cick Add Directory and then select Add Active Directory.
- Click Set Up Active Directory.
- Click Download Agent.
- Double click the file to launch the installer.
- Click Yes at the message Do you want to allow the following program to make changes to this computer?.
- Choose an installation destination.
- Select the AD domain you want to manage with this agent.
- Select Create or use the Okta Service account (recommended) and complete the prompt to set a password.
Note: Select Use an alternate account that I specify if you want to assign the Okta AD Agent to run as an existing domain user.
- (Optional) If appropriate for your environment, specify a proxy server through which your AD agent will connect.
- To register the AD Agent with the Okta service, enter your Okta subdomain name, and then click Next.
- Enter the username and a password, and then click Sign in.
- Click Allow Access.
Note: If the error message displays The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel, see Troubleshooting.
- Click Finish.
- When the Active Directory agent has started, click Next.
- (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 groups. You can change these and other settings at any time.
- Select the Okta Username format that you want AD-imported end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using chiclets to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. to use when logging in to Okta.
- Click Next.
- In the Build User Profile tab, select the attributes that you want to use to build your Okta user profiles.
- Click Next.
- When the initial Active Directory agent configuration is complete, click Next.
- Click Done.
- 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 Configuring Import and Provisioning Settings.
- Click Save Settings.
- If you installed the AD agent on a DMZ server, you must open several ports.
- 135/TCP RPC
- 137/UDP NetBIOS
- 138/UDP NetBIOS
- 139/TCP NetBIOS
- 389/TCP/UDP LDAP
- 636/TCP LDAP SSL
- 3268/TCP LDAP GC
- 3269/TCP LDAP GC SSL
- 53/TCP/UDP DNS
- 88/TCP/UDP Kerberos
- 445/TCP SMB
- 123/UDP NTP
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
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
- In Windows, select Start > Control Panel > Programs > Programs and Features.
- Select the Okta AD Agent, and then select Uninstall.
- Uninstalling your AD agent leaves the agent configuration data on your hard drive.
- To remove the configuration data, go to C:\Program Files (x86)\Okta and delete the Okta AD Agent folder. Deleting this folder removes the agent configuration data and the API Token from your hard drive. The API token for the server is still valid in Okta so it is important to remove the configuration data.
- Revoke the API token by going to the agent monitor. Deactivate and remove the uninstalled agent, which will remove the API token.
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:
- Perform the AD agent installation procedure described in Installing the Active Directory Agent.
- Select Directory > Directory Integrations.
- Click Active Directory.
- In the Settings tab, your agents are listed in the Agent Monitors section. Confirm that your reinstalled AD agent is connected to Okta and appears in the list. You should always make sure to have at least one AD agent online.
If you are performing an upgrade or reinstallation 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.
- Under Agent Monitors, select the Deactivate link for the old AD agent and then click Ok to confirm. Deactivating the agent revokes its API token.
- Click the Remove link for the old AD agent and then click Ok to confirm.
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 orgAn abbreviation of organization, but can also be thought of as a company. A company that uses Okta as their SSO portal is generally referred to as an org. As an administrator, you decide how Okta should be displayed and/or integrated with your 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:
- 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.
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.
- User OUs connected to Okta – Select the organizational units from which to import users.
- Group OUs connected to Okta – Select the organizational units from which to import groups.
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.
- User filter – sAMAccountType=805306368
- Group filter – objectCategory=group
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.
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 SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones. 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 to create new users in Okta via JIT, not via imports, yet continue to use imports to sync groups and group memberships.
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.
Note: All Okta users can sign in by entering the alias part of their usernames 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.
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, and/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.
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. Select the automatic confirmation option that matches the policies of your organization:
Note: This feature does not apply to CSV-imported user lists.
EXACT IMPORT MATCH – 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.
- Imported user is exact match if – Select 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. In order 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.
- When exact match found – Specify whether matches are confirmed automatically or manually once the matching status is established. If manually confirmed, you must activate the user in Directory > People.
PARTIAL IMPORT MATCH – 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.
- Imported user is partial match if – Define the match criteria that establishes whether an imported user partially matches an existing Okta user.
Note: This option is selected by default. When it is selected and the option Auto-confirm match in the When partial match found setting (below) is also selected, importing users from multiple AD domains may result in one or more merged accounts if any imported users have the same name as existing Okta users.
- When partial match found – Specify whether matches are confirmed automatically or manually once the matching status is established. If manually confirmed, you must activate the user in Directory > People.
NO IMPORT MATCH – Define what constitutes a user who would not be associated with an existing Okta user.
- When no match found – Specify whether matches are confirmed automatically or manually once the matching status is established.
- Auto-activate after confirmation – Select to automate the activation of the 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.
- Activation email recipient – Specify where to send the new AD account credentials. The recipient is responsible for distributing the credential information to the appropriate user.
- AD username format – Specify a default AD username format.
- AD common name format – Specify a default AD common name format.
- Exclude AD username update – If you select this option, Okta does not update the usernames of existing AD accounts that are Okta mastered when you change the default username format. You can still provision new AD accounts from Okta.
Update User Attributes
Okta updates a user's attributes in Active Directory when the 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. is assigned. Future attribute changes made to the Okta user profile automatically overwrite the corresponding attribute value in Active Directory.
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 sync'd to Okta during provisioning events. AD defaults as a 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 Using the Okta People Page., 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
- 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.
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.
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.
Okta’s 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.
- On your Windows desktop, select Start > All Programs > Okta > Okta AD Agent > Okta AD Agent Manager.
- Select Domains.
- In the drop-down menu containing the grayed-out text choose another domain, select the domain that you want to add, and then click Register. Alternatively, you can type the desired domain name in the drop-down field, and then click Register.
- A message appears stating that your new domain has been registered and prompting you to restart the agent. Optionally register additional domains. Restart your AD agent after you are finished.
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:
- Select Directory > Directory Integrations.
- Click Active Directory.
- Select the Settings tab. Your agents are listed in the Agent Monitors section.
- Click Add Agent.
- Run the installer as described in Installing the Active Directory Agent.
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
- Sign in to the server running the AD Agent.
- From the Start menu, type run, then type services.msc.
- Locate the Okta AD Agent Service.
- Right click the Okta AD Agent Service and select Properties.
- Select the Log On tab and change the account credentials.
- Restart the service and verify that the agent displays as green in your Okta org.
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:
- Before opening or modifying the AD agent configuration files, stop the AD agent service under Windows Services.
- From the terminal, locate the OktaAgentService.exe.instances.config file for each AD agent server:
C:\Program Files (x86)\Okta\Okta AD Agent\OktaAgentService.exe.config
Open the 'OktaAgentService.exe.config' file in a suitable text editor program and then locate the following line:
<add key="PollingThreads" value="2" />
The default value is 2 and the valid range is 1 - 10. As an example to increase the number of polling threads to four, edit the line to look like this:
<add key="PollingThreads" value="4" />
- Save the file.
- Start the agent.
Once the change has been made, save the file and then start the Okta AD agent service again. You can verify that the setting has changed by opening the agent.log file at startup and observing the startup information towards the bottom of the file:
2017/07/21 06:06:22.167 Debug – TEST-SERVER-1(4) – PollingThreads: 4
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
- Perform steps 1 through 4 of the procedure Installing the Active Directory Agent.
- Instead of double-clicking the file as directed in step 5, open a command line terminal and enter the following:
- Press Enter.
- Complete the installation as described in Installing and Configuring the Agent.
To re-enable support for SSL certificate pinning if it is disabled
- Locate and open the AD agent configuration file:
C:\Program Files (x86)\Okta\Okta AD Agent\OktaADAgentSetup.exe.config
- Change the SSL pinning enabled setting to True:
- Save the configuration file and restart the agent.