Synchronize passwords from Active Directory to Okta

You use the Okta AD Password Sync Agent to synchronize passwords from Active Directory (AD) to Okta and to integrated apps with password synchronization.

When delegated authentication to AD is enabled, directory passwords are not synchronized to Okta because delegated authentication performs the authentication and there is no Okta password. With delegated authentication users use their directory password to sign on to Okta.

Occasionally, directory passwords need to be synchronized from a directory through Okta to an application. To accomplish this synchronization, a user uses their directory password to sign on to Okta. Okta checks the password and then determines if the user is assigned to an application using password synchronization. If there are no assigned applications using password synchronization, the password is cached for five days. If the application uses password synchronization, the password is synchronized to the application, the password is stored in Okta as the application password, and then the directory password is cached for five days.

If users sign in to Okta using Desktop Single Sign-on (DSSO) instead of using a username or password, the Password Sync Agent is required to track password changes in AD and then synchronize the changes to Okta. Alternatively, you can ask your users to change their AD passwords in Okta or ask them to sign in to Okta after a password change in AD to sync their password with applications.

The scenarios described in the following table are intended to help you determine if you need to install the Okta AD Password Sync Agent.

Scenario User Experience Outcome
Okta is connected to an AD domain. An Okta AD Password Sync Agent is not deployed.
  • The user changes their password from their workstation sign in screen.
  • The user signs on to their device.
  • The user attempts to sign in to another application with password synchronization.
 The user receives a password error message because the new password has not been synced to the application. To synchronize the new password to Okta integrated apps, users need to sign out from Okta and then sign in to Okta.
Okta is connected to an AD domain and Desktop Single Sign-on (DSSO) is implemented. An Okta AD Password Sync Agent is not deployed. The user receives a password error message because the new password has not been synced to the application. To synchronize the new password, users need to sign out from Okta and then sign in to Okta.
Okta is connected to an AD domain and DSSO may or may not be implemented. An Okta AD Password Sync Agent is installed on every domain controller in the domain. The user accesses the application successfully. The Okta AD Password Sync Agent intercepted the password change event and pushed it to Okta.

Active Directory password reset workflow

When a user changes their AD password in Okta, Okta uses the AD Agent to send the request to AD. An AD password reset is not a password synchronization event.

This is a typical password reset workflow:

  • A user unsuccessfully attempts to sign on to Okta.
  • The user requests a password reset.
  • The user successfully answers the forgotten password question or SMS authentication which includes a forgotten password question.
  • The user is authenticated to Okta, but not AD.
  • The user is asked to enter a new password.
  • The new password is temporarily held by Okta.
  • Okta pushes the password to AD. This requires elevated permissions on the Okta Active Directory (AD) agent service account.
  • The AD password reset activates password synchronization to applications using password synchronization.
  • Okta forgets the password.

Before you begin

  • You have an AD domain integrated with Okta.
  • The Okta Active Directory (AD) agent is installed and configured in each integrated domain in your forest.
  • The Okta AD Password Sync Agent is installed and configured on all domain controllers in each integrated domain in your forest.
  • Delegated Authentication is enabled. For more about Delegated Authentication, see Authentication.
  • The Okta username format must be UPN or SAM Account Name. If you have mapped Active Directory to Okta using any other username format the Okta AD Password Sync Agent will fail.
  • To improve the security of our integrations, we now only communicate using the TLS1.2 security protocol. For Windows 2008 R2 TLS 1.2 is disabled by default and must be enabled through the registry. If you have Windows 2008 R2, ensure the following regkeys are set correctly:

    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "Enabled"=dword:00000001

    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "DisabledByDefault"=dword:00000000

    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] "Enabled"=dword:00000001

    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] "DisabledByDefault"=dword:00000000

Install the Okta AD Password Sync Agent

When installing Okta Active Directory Password Sync Agent versions 1.4.0 and later, the Microsoft Visual C++ Redistributable for Visual Studio 2019 is installed if it hasn't been installed previously.

  1. On the domain controller, go to the Okta Admin Console, click SecurityDelegated Authentication and in the right pane scroll down and click Download Okta AD Password Sync.
  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 Okta AD Password Sync Agent, and then click Install.
  5. Click Finish.
  6. Restart the server.
  7. Optional. Repeat steps 1 to 6 on every domain controller in your forest that you want to integrate with Okta.

Unattended installation

You can use a script or a command to perform an unattended install of the Okta AD Password Sync Agent. The unattended mode does not restart the system after the installation is complete. You must restart the system manually or use the shutdown /r command.

The syntax for an unattended installation is: 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 want to create a registry file that sets the Okta username format used by the Okta AD Password Sync Agent. Creating a DWORD Value called Okta Username Format allows 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

Install the Okta 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 hotfix from here: 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 Okta AD Password Sync Agent does not support the management console and you must use regedit to disable the setting. You can monitor the Okta AD Password Sync Agent logs located at: %ProgramData%\Okta\AD Password Sync\logs.

  4. Install the Okta AD Password Sync Agent. See Install the Okta Password Sync agent.

Configure the Okta AD Password Sync Agent

  1. Click StartAll ProgramsOkta Okta AD Password SyncOkta 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 appears below the Okta URL field.

Note: If an error message appears, see Troubleshoot password synchronization.

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: Logs info and error events. This is the default logging level .
  • Error: Logs error events only.