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 aren't synchronized to Okta because delegated authentication performs the authentication and there's 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 isn't deployed.
  • The user changes their password from their workstation sign-in page.
  • 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 hasn't 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 isn't deployed.
  • The user changes their password from their workstation sign-in page.
  • The user signs on to their device.
  • The user attempts to sign in to another application that uses password sync.
 The user receives a password error message because the new password hasn't 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 changes their password from their workstation sign-in page.
  • The user signs on to their device.
  • The user attempts to sign in to another application that uses password sync.
 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 isn't 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 an SMS authentication that 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. The Okta AD Password Sync Agent fails if you map Active Directory to Okta using any other username format.
  • The TLS 1.2 security protocol is used to improve the security of our integrations. 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 that 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 doesn't restart the system after the installation is complete. Either restart the system manually or use the shutdown /r command.

The syntax for an unattended installation is: msiexec /i OktaPasswordSyncSetup-<version>.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 Microsoft.

  2. If you're 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 doesn't support the management console and you must use regedit to disable the setting. You can monitor the Okta AD Password Sync Agent logs, which are stored under: %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.