Configure device management profiles for Desktop Password Sync

Early Access release. See Manage Early Access and Beta features.

Set up Desktop Password Sync for macOS and create managed profiles to enable the password sync workflow on your devices. You can use any device management solution that supports extensible SSO payload deployment with platform SSO authentication enabled. These instructions assume you're using Jamf Pro for device management.

Desktop Password Sync for macOS requires three types of payloads for full functionality:

  1. An extensible single sign-on profile deployed at the computer level.

  2. An AssociatedDomain payload. This can be within the same profile as the extensible single sign-on extension.

  3. A managed app configuration, containing the org URL, username, and client ID. The username and client ID are specific to Desktop Password Sync, and need to be scoped to the SSO extension domain only. A separate entry should be added for each Okta preference domain.

You're asked to provide an org URL at several points during the setup process. For example, https://customerorg.okta.com. Use the same org URL wherever you're prompted to provide an org URL. If you have a custom domain configured, then use the custom domain URL.

Tasks

Create a single sign-on extension profile

The SSO extension extends to the macOS sign-in window, which enables users to use their Okta credentials to unlock their computer. The local account password is automatically kept in sync, so the local password and Okta password match.

You may already have a Single Sign-On Extension (SSOE) profile set up for Okta Verify. A second SSOE profile is required for Desktop Password Sync. Create the profile in your device management software with the following parameters:

  • Payload type: SSO

  • Extension identifier: com.okta.mobile.auth-service-extension

  • Team identifier: B7F62B65BN

  • Sign-on type: Redirect

  • URLs: Add your Okta org URL with the path /device-access/api/v1/nonce and /oauth2/v1/token. See the following examples:

    • https://customerorg.okta.com/device-access/api/v1/nonce

    • https://customerorg.okta.com/oauth2/v1/token

  • Use Platform SSO: Enabled

  • Authentication method: Password

In the same profile, configure the Associated Domains field. Use B7F62B65BN.com.okta.mobile.auth-service-extension as the App Identifier. The format for the Associated Domain is your org URL with authsrv: preceding the URL, for example, authsrv:customerorg.okta.com. For more information, review Apple's AssociatedDomains documentation.

Create a device management profile

A managed app configuration allows you to enable the functionality that is built into macOS Okta Verify and Desktop Password Sync.

Create a new managed app configuration for macOS devices. In the new profile, click Applications & Custom Settings Upload +Add to create a separate payload entry for each of the two Okta preference domains. You can use the same property list in both entries:

Preference Domain Example Comment
com.okta.mobile <plist version="1.0"> <dict> <key>OktaVerify.OrgUrl</key> <string>https://customerorg.okta.com</string> <key>OktaVerify.UserPrincipalName</key> <string>$USERNAME</string> </dict> </plist>

If this has already been configured for Okta Verify or Okta FastPass, you don’t need to create it again. The same configuration can be used for Desktop Password Sync.
com.okta.mobile.auth-service-extension <plist version="1.0"> <dict> <key>OktaVerify.OrgUrl</key> <string>https://replace-with-your-org-URL</string> <key>OktaVerify.UserPrincipalName</key> <string>$USERNAME</string> <key>OktaVerify.PasswordSyncClientID</key> <string>replace-with-your-client-ID</string> </dict> </plist>

Replace the strings for your org URL and client ID. Use the same org URL (https://customerorg.okta.com) throughout the Desktop Password Sync setup process. See Configure Desktop Password Sync for macOS for your client ID.

$USERNAME is an optional value for OktaVerify.UserPrincipalName, which automatically populates the username in the Sign-In Widget. If a value isn't specified, users need to input their username when signing in.

Distribute the profile to all computers in scope, or distribute to newly assigned devices only.

After creating and distributing the device management profile, notify your end users about the upcoming changes to their sign-in experience. Users see a system notification informing them that registration is required to sync their local macOS password to their Okta password. Desktop Password Sync also sets up Okta FastPass as part of the enrollment process. If you have biometrics for Okta FastPass set to required or optional, the Desktop Password Sync enrollment flow prompts users for Touch ID to successfully set up Okta FastPass.

Generic MDM setup

If you don't use Jamf Pro as your mobile device manager, use these generic profile examples to configure the required payloads for Desktop Password Sync.

Payload Example
com.apple.com.associated-domain <key>PayloadType</key>
<string>com.apple.associated-domains</string>
<key>Configuration</key>
<array>
<dict>
<key>ApplicationIdentifier</key>
<string>B7F62B65BN.com.okta.mobile.auth-service-extension</string>
<key>AssociatedDomains</key>
<array>
<string>authsrv:customerorg.okta.com</string>
</array>
</dict>
</array>
com.apple.extensiblesso <key>PayloadType</key>
<string>com.apple.extensiblesso</string>
<key>AuthenticationMethod</key>
<string>Password</string>
<key>ExtensionIdentifier</key>
<string>com.okta.mobile.auth-service-extension</string>
<key>Hosts</key>
<array/>
<key>TeamIdentifier</key>
<string>B7F62B65BN</string>
<key>Type</key>
<string>Redirect</string>
<key>URLs</key> <array> <string>https://customerorg.okta.com/device-access/api/v1/nonce</string> <string>https://customerorg.okta.com/oauth2/v1/token</string> </array>
com.okta.mobile <key>PayloadType</key> <string>com.okta.mobile</string> <key>OktaVerify.OrgUrl</key> <string>https://customerorg.okta.com</string> <key>OktaVerify.UserPrincipalName</key> <string>username@domain.com</string>
com.okta.mobile.auth-service-extension <key>PayloadType</key> <string>com.okta.mobile</string> <key>OktaVerify.OrgUrl</key> <string>https://customerorg.okta.com</string> <key>OktaVerify.PasswordSyncClientID</key> <string>your-client-ID</string> <key>OktaVerify.UserPrincipalName</key> <string>username@domain.com</string>

Next steps

Troubleshoot Desktop Password Sync for macOS