Install and configure the Password Sync Agent Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a000000u90osas&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2finstall-and-configure-the-password-sync-agent-1709598269
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Install and configure the Password Sync Agent
Published: Feb 14, 2018   -   Updated: Jun 22, 2018

 

 

okta-doc-source

Install and Configure the Active Directory Password Sync Agent

Install the Active Directory (AD) Password Sync agent on domain controllers in your domain to synchronize AD password changes and send them to Okta automatically. This functionality keeps your users' AD passwords in sync with apps that are configured to use Sync Password, such as SWA apps set up to use the user's Okta password.

However, for mobile workflows, AD password resets from the Active Directory Password Sync Agent do not require sync password to be enabled. Reset password notifications trigger distribution of an updated Exchange ActiveSync (EAS) email configuration to the corresponding devices enrolled in Okta Mobility Management (OMM). In such cases where sync password is not enabled for any application, the encrypted AD password is removed from Okta after pushing it to the device.

If you've integrated AD and desktop SSO, configured apps to delegate authority to AD, and your users change their AD passwords through their machine sign-in prompt, the AD Password Sync agent detects this change and sends it to Okta automatically so that when your users sign in, change their passwords, and click on apps they use, their new passwords are automatically synced.

If you have integrated AD and configured provisioning with sync password enabled (for example, pushed your Okta password to Google Apps), the AD Password Sync agent detects a user's password change and makes sure the passwords are automatically synced. For devices enrolled in Okta Mobility Management (OMM), sync password does not need to be enabled.

Deciding whether to implement the Password Sync agent

Implementing the Password Sync agent requires you to install the agent on each domain controller. As agent updates are released, each domain controller must then have its agents updated. As a result, you may wish to balance the benefits which the Password Sync agent offers against the internal cost of maintaining the agents on your domain controllers. This decision will vary based on end user behavior within your organization, your application environment and your IT infrastructure.

When making your decision, consider these scenarios which may occur if Password Sync is not employed:

ScenarioUser ExperienceOutcome
Okta is connected to an Active Directory and LDAP server. No Password Sync agent is deployed.
  1. The user changes their password from their workstation sign in screen.
  2. The user is signed on to their device.
  3. They then attempt to sign in to another application connected to an LDAP server.
The user will get a password error, because the new password will not have synced to LDAP. It will not be clear to the user that they must use their old password at this time.
Okta is connected to an AD Domain with Desktop SSO deployed. No Password Sync agent is deployed. LDAP may also be deployed.The user will get a password error, because the new password will not have synced. It will not be clear to the user that they must use their old password.
No Desktop SSO is configured. No apps are connected to Okta that are using Password Sync or Push.Users must know to sign in each time after changing their password to ensure Okta captures the new password.

To use the agent, see Using Sync Password.

Requirements
  • Windows Server 2008 and later
  • Windows Server Core, Release 2
  • Install and configure the Okta AD agent on at least one domain-joined server in each domain in your forest (does not need to be a Domain Controller), and then install the Okta AD Password Sync agent on all of the domain fin each domain.
  • Ensure that the Okta username format is set to User Principal Name (UPN) or sAMAccountName in your AD Import and Provisioning settings (Directory > Directory Integrations > Settings). For more information, see Installing and Configuring the Active Directory Agent.

    Note: If you have mapped Active Directory to Okta using any other username format the Password Sync Agent will fail.

  • This feature requires that Delegated Authentication be enabled on your Okta org. For more about Delegated Authentication, see Authentication.
Installing the AD Password Sync Agent
  1. Download the appropriate version of the agent:
    • For the executable (.exe) version, go to Settings > Downloads > AD Password Sync Installer or Security > Delegated Authentication, look in the AD Password Sync sidebar, and then click Download Okta AD Password Sync
    • For the Microsoft Installer (.msi) version, go toSettings > Downloads > AD Password Sync (Windows Installer)
  2. Double-click the installer file and follow the prompts.
  3. When prompted, enter your Okta URL. For example, https://mycompany.okta.com. You must use the https:// protocol in your entry.
  4. When prompted, choose where you want to install the AD Password Sync agent, and then click Install.
  5. Click Finish.
  6. Restart your system.

Unattended installs

You can also use a script or command line to perform an unattended install of the agent. The unattended mode will not restart the system after the installation is complete. You must restart the system manually or using the shutdown /r command. The syntax is as follows:

  • OktaPasswordSyncSetup.exe /install /q2 OktaURL=https://mycompany.okta.com

    or

  • msiexec /i OktaPasswordSyncSetup.msi /quiet EXEOPTIONS="/q2 OktaURL=https://mycompany.okta.com"

If installing on multiple servers, you may wish to create a registry file that sets the Okta username format used by the Password Sync Agent. Creating a DWORD Value called Okta Username Format will allow you to choose between SAM Account Name (value = 1) or UPN (value = 0).

For example, to set the Username format to SAM Account Name, create a .reg file with the following:

[HKEY_LOCAL_MACHINE\SOFTWARE\Okta\AD Password Sync]

"Okta username format"=dword:00000001

Installing the AD Password Sync Agent on Windows Server Core, Release 2

Before you can install the Active Directory (AD) Password Sync agent on Windows Server Core, you must do the following:

  1. Install the following hotfix before installation: http://support.microsoft.com/kb/2624641

  2. If you are downgrading to an earlier version of the agent, manually uninstall previous versions of the Tarma installer. The uninstaller is located here:

    %ProgramData%\InstallMate\{5433CCD3-328D-4326-9E1A-56C9B1D3A7E1}\Setup.exe

    To perform an unattended uninstall: %ProgramData%\InstallMate{5433CCD3-328D-4326-9E1A-56C9B1D3A7E1}\Setup.exe /remove /q2

  3. The AD Password Sync agent does not support the management console and you must use regedit to disable the setting. You can monitor the AD Password Sync logs located at: %ProgramData%\Okta\AD Password Sync\logs

You can now install the AD Password Sync agent as described in Installing the AD Password Sync Agent above.

To use the agent, see Using Sync Password.

Configuring the AD Password Sync Agent
  1. Launch the Active Directory Password Sync Agent (Start > All Programs > Okta > Okta AD Password Sync > Okta AD Password Synchronization Agent Management Console).
  2. Click Verify URL to check the Okta URL is correct and the target server is reachable. If the URL is valid, a success message will appear under the Okta URL field.

Note: If an error message displays, see Troubleshooting.

You can optionally change the Log severity level setting. You can control the information that goes into logging reports by selecting one of the following options:

  • None – Logs nothing.
  • Debug – Logs debug, info and error events.
  • Info – This is the default logging level and it logs info and error events.
  • Error – Logs error events only.
Troubleshooting

This section describes error conditions and how to correct them.

The agent is installed on all Domain Controllers, user's AD password has changed, but user is not able to log in to apps via desktop SSO

The problem may be that the Okta username format for your org is not set to User Principal Name (UPN) or sAMAccountName. In most cases, the Okta username format must be set to User Principal Name (UPN) or sAMAccountNamein order for the AD Password Sync Agent to work.

To check the setting, do the following:

  1. Log in to your Okta Admin Dashboard.
  2. Go to Directory > Directory Integrations > Settings.
  3. Under Import and Provisioning make sure that User Principal Name or sAMAccountNameis selected in the Okta username format picker.

Filter was loaded successfully, but is not enabled

If you launch the AD Password Sync agent and a message displays stating that the agent is not enabled, you must enter your Okta URL (for example, https://mycompany.okta.com) and click Verify URL.

Note: You must use the https:// prefix in your entry.

AD_PW_Sync_VerifyURL_517x201

Password filter failed to load

If you launch the AD Password Sync agent and a message displays stating that the password filter failed to load, contact Okta support.

Could not establish trust relationship

If you launch the AD Password Sync agent and the message displays The underlying connection was closed. Could not establish trust relationship for the SSL/TLS secure channel, then you installed AD Password Sync agent version 1.3.0 or later 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, you can choose to disable SSL certificate pinning as described below, but be aware that doing so disables a security enhancement provided by the agent.

To disable support for SSL pinning, edit the Windows registry as follows:

  1. Go to the Start menu and type regedit in the search box.
  2. If a message displays Do you want to allow the following program to make changes to this computer?, click Yes.
  3. In the Registry Editor, navigate to HKEY_LOCAL_MACHINE > SOFTWARE > Okta > AD Password Sync.
  4. Double-click the setting Enable certificate pinning and change the value to 0.
  5. Click OK to save your change.

For more information about SSL certificate pinning, see the article by the Open Web Application Security Project.

Top