Support your Desktop Password Sync users

When users register their macOS device and link the local computer account with an Okta account, the device password and the Okta password sync. The device password is replaced with the Okta password. The synced password can access anything that previously required the local account password. If a user changes their Okta password, they need to lock the computer and then unlock it with the updated password for the service to sync the device and the IdP password.

To prepare users for the changes to their sign-in flow, Okta has prepared a series of templates to communicate Desktop Password Sync plans. Download the templates from the Launch Kit for Okta Admins, and use the appropriate wording to explain the new authentication process to users.

Establish a bug reporting channel

Ask users to report issues or bugs in Okta Verify from their mobile device. The Menu bar of their Okta Verify mobile app contains a Send Feedback link. Users should tap Report a bug and fill out the form. System Logs are automatically attached, and the report is sent to Okta. Users should then contact someone within your organization for assistance signing in to the computer.

Password synchronization

A user's password is synchronized at specific points in the workflow. Consult the table to determine the expected behavior from Desktop Password Sync.

Behavior

Result

User completes Desktop Password Sync registration. Password syncs if the local account password is different from the Identity Provider password.
User changes local account password. Password syncs if the user enters their Identity Provider password to unlock the device, or when the system notification appears, prompting the user to sign in to their Identity Provider account upon token expiration.
User changes the Identity Provider password. Password syncs if the user enters their Identity Provider password to unlock the device, or when the system notification appears, prompting the user to sign in to their Identity Provider account upon token expiration.
User enters a changed Identity Provider password at the device sign-in screen. Sign in fails. Platform Single Sign-on doesn't support password synchronization at the sign-in window. Users must enter their old password to sign in, and then they're prompted to resync the device to their new password.
User changes a password locally using the macOS Password Expiration prompt.

Sign in fails. This password isn't synced with Okta, and the password attempts to revert to a previous password. This isn't possible due to the MDM password policies in place.

In your MDM, disable local password expiration for the affected user's macOS accounts. The macOS password expiration policy is redundant with the Okta password policy, and isn't compatible with Desktop Password Sync.

See Configure the password authenticator.

Resolve password issues

If you have an MDM password policy (for example, a minimum password length) and the user's Okta password doesn't satisfy the requirements, the password sync fails. The user sees Apple's visual indicator that the password is incorrect, even if the credentials are entered correctly. To work around this issue, try one of the following methods:

  • Change the MDM password policy to match the Okta password requirements.

  • Change the Okta password requirements to match the MDM password policy. See Configure the password authenticator.

  • Ask users to sign in to the End-User Dashboard and update their Okta password to meet the MDM policy requirements.

  • Ask users not to reuse old passwords.

  • Disable the macOS account password expiration option in your MDM.

Resolve registration issues

If users are experiencing registration issues and can't complete the registration steps, the user needs to re-register their device and go through the registration process again.

Deleting a device or user doesn't reset the registration. Follow the steps for the appropriate operating system to reset a registration.

macOS Sonoma

Users on macOS Sonoma can initiate a registration reset on their own.

  1. On the macOS device, open System Settings Users & Groups.

  2. Click the information icon in the row with the user's account.

  3. Under the Platform Single Sign-on heading, locate the Registration line and click Repair.

  4. Follow the prompts to re-register the device and sync the user's password.

If these steps don't resolve the user's registration issues, follow the steps outlined for a macOS Ventura registration reset.

macOS Ventura

If users don’t receive the registration required notification, you can reset the registration for the device to remove and then reassign the payload to the device.

  1. In your MDM, look for the Desktop Password Sync configuration profile you created.

  2. Open the profile and click Edit.

  3. On the Scope tab, remove the target for the device you want to reset.

  4. Save the changes.

  5. Redistribute the profile to all devices.

  6. On the macOS device, confirm that the profile has been removed from Privacy & Security Profiles.

  7. Ensure that all SSO extension profiles, including credential extensions and extension profiles from other Okta products, have been removed.

  8. Restart the device.

  9. In your MDM, reassign the profile to the device.

  10. On the macOS device, confirm that the profile was pushed to the device successfully.

  11. Wait for the registration request notification, and then register the device.

Known issues

  • Using Okta Desktop Password Sync with other password syncing solutions can cause rate limit issues and other unexpected behavior. To resolve this issue, disable other solutions that synchronize the local account password with Okta.

  • If a user performs an action that wipes the keychain, it also removes the Desktop Password Sync registration, which puts the application in an invalid state. To resolve this issue, users need to complete the registration reset steps outlined for the appropriate macOS version. These are some examples of actions that can wipe the keychain:

    • A password reset using recovery flow.

    • Reinstalling or resetting the operating system.

    • Manually deleting the keychain.

  • If a user's password is in an invalid state, Desktop Password Sync could fail to sync. These are some actions that can lead to an invalid password state:

    • Expired passwords.

    • User is locked out due to multiple invalid password attempts.

    • Admin has forced the user to reset their current password and the user hasn't yet created a password.

    • Admin has created a temporary one-time password and the user hasn't yet updated the password.

  • Customers deploying Desktop Password Sync on non-English macOS computers should deploy Okta Verify version 9.1.0 or newer. Previous versions of Okta Verify may fail to complete enrollment on macOS computers using languages other than English.

  • In Okta Verify version 9.0, the Desktop Password Sync registration fails if your org has a custom domain. The issue has been resolved in Okta Verify version 9.1. If you encounter registration errors, ensure you're using Okta Verify version 9.1.

  • If you have Okta Verify and Desktop Password Sync running and try to delete the app, an error is displayed stating that the app can't be deleted due to extensions running. To work around this issue, upgrade macOS to version 13.5, or try the following steps:

    1. Quit the Okta Verify app.

    2. Quit Okta Verify's SSO extension (SSOe):

      1. In terminal, enter the command ps -ax | grep AppSSOAgent.

      2. If there's only one entry in the list of results, then your Okta Verify's SSOe isn't running

      3. If there's more than one entry, copy the pid of the first one.

      4. In a terminal, enter the command kill <pid>.

      5. Run the ps -ax | grep AppSSOAgent command again and ensure you only see one entry.

    3. Delete the Okta Verify app.

Related topics

Okta Device Access support hub