Configure device configuration profiles for PSSO using a generic MDM

This guide provides general instructions to configure Platform Single Sign-on (Platform SSO) for macOS using a Mobile Device Management (MDM) solution. If you're using Microsoft Intune, Jamf Pro, or Workspace ONE, refer to the appropriate guide for your MDM.

This guide is intended for admins using an MDM such as Kandji or Mosyle that supports the deployment of custom configuration profiles and managed app configurations. For detailed guidance on creating and deploying these types of profiles, refer to the documentation for your MDM solution.

For a full explanation of the benefits, prerequisites, and version compatibility of PSSO, see Platform SSO for macOS.

Before you begin

Add and configure the Platform SSO app.
Confirm that you have configured and deployed Device Access certificates to your macOS devices.
User devices must be running macOS 14 Sonoma or later.
Download the Okta Verify PKG file from the Okta Admin Console. See Download Okta Verify for macOS.

Start this task

To use PSSO, create and deploy configuration profiles that contain the following payloads.

An extensible single sign-on profile deployed at the computer level.
An associated domain payload. This can be within the same profile as the Single Sign-On (SSO) extension.
A managed app configuration that contains the org URL, username, client ID, and Platform SSO protocol version. The username and client ID are specific to Desktop Password Sync. Scope the username and client ID to the SSO extension domain only. Add a separate entry for each Okta preference domain.

Most MDM solutions allow you to upload custom .plist files that contain these profiles.

In this guide, when you provide your org's URL, for example, https://customerorg.okta.com, use the same org URL each time.

If you have configured a custom domain, then use that custom domain URL.

Configure the SSO profile

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

This is the primary payload that enables PSSO and directs macOS to use Okta Verify for authentication.

Key	Value
Payload Type	com.apple.extensiblesso
Extension Identifier	com.okta.mobile.auth-service-extension
Team Identifier	B7F62B65BN
Type	Redirect
Authentication method	Password
Use Shared Device Keys	True (enabled)
Use Platform SSO	True (enabled)
Enable registration during setup	For orgs using Platform SSO 2.0 with macOS 26 Tahoe, set this to True (enabled).
Account Display Name	The display name used in notifications and authentication requests for the account. This is set at the system level, not at the level of a specific user account, so this value is visible to all users.
URLs	Add the URLs for your Okta org, including the paths: /device-access/api/v1/nonce /oauth2/v1/token /v1/auth/device-sign For example: https://customerorg.okta.com/device-access/api/v1/nonce https://customerorg.okta.com/oauth2/v1/token https://customerorg.okta.com/v1/auth/device-sign

Generic MDM example

Copy

<key>PayloadType</key>
<string>com.apple.extensiblesso</string>
<key>PlatformSSO</key>
<dict>
    <key>AuthenticationMethod</key>
    <string>Password</string>
    <key>UseSharedDeviceKeys</key>
    <true/>
</dict>
<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>
    <string>https://customerorg.okta.com/v1/auth/device-sign</string>
</array>

Kandji example

Copy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>PayloadContent</key>
        <array>
            <dict>
                <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>
                <key>PayloadDisplayName</key>
                <string>Associated Domains for Okta Verify</string>
                <key>PayloadIdentifier</key>
                <string>F65C9B21-13AD-4F46-86E5-C3352E7D97B6</string>
                <key>PayloadOrganization</key>
                <string>CUSTOMER NAME</string>
                <key>PayloadType</key>
                <string>com.apple.associated-domains</string>
                <key>PayloadUUID</key>
                <string>F65C9B21-13AD-4F46-86E5-C3352E7D97B6</string>
                <key>PayloadVersion</key>
                <integer>1</integer>
            </dict>
            <dict>
                <key>PlatformSSO</key>
                <dict>
                    <key>AuthenticationMethod</key>
                    <string>Password</string>
                    <key>UseSharedDeviceKeys</key>
                    <true/>
                </dict>
                <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>
                <key>PayloadDisplayName</key>
                <string>Okta Verify Sign-On Extensions Payload</string>
                <key>PayloadIdentifier</key>
                <string>77058B08-6943-4DEC-899A-721F55B4EEE8</string>
                <key>PayloadOrganization</key>
                <string>CUSTOMER NAME</string>
                <key>PayloadType</key>
                <string>com.apple.extensiblesso</string>
                <key>PayloadUUID</key>
                <string>77058B08-6943-4DEC-899A-721F55B4EEE8</string>
                <key>PayloadVersion</key>
                <integer>1</integer>
            </dict>
        </array>
        <key>PayloadDescription</key>
        <string>Okta PSSO extension configuration</string>
        <key>PayloadDisplayName</key>
        <string>Okta PSSO extension</string>
        <key>PayloadIdentifier</key>
        <string>com.customer-name.profiles.ssoextension</string>
        <key>PayloadOrganization</key>
        <string>CUSTOMER NAME</string>
        <key>PayloadScope</key>
        <string>System</string>
        <key>PayloadType</key>
        <string>Configuration</string>
        <key>PayloadUUID</key>
        <string>D78FE406-0C61-4007-8C51-FFA5FDE5F54B</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
    </dict>
</plist>

Configure associated domains

This payload securely links your Okta org URL to the Okta Verify app.

Key	Value
Payload	com.apple.associated-domains
Application Identifier	B7F62B65BN.com.okta.mobile B7F62B65BN.com.okta.mobile.auth-service-extension
Associated Domains	Add the URL domain for your Okta org, for example, authsrv:customerorg.okta.com Each app identifier needs an associated domain.

Key

Value

Payload

com.apple.associated-domains

Application Identifier

B7F62B65BN.com.okta.mobile

B7F62B65BN.com.okta.mobile.auth-service-extension

Associated Domains

Add the URL domain for your Okta org, for example, authsrv:customerorg.okta.com

Each app identifier needs an associated domain.

Generic MDM example

Copy

<key>PayloadType</key>
<string>com.apple.associated-domains</string>
<key>AssociatedDomains</key>
<array>
    <dict>
        <key>ApplicationIdentifier</key>
        <string>B7F62B65BN.com.okta.mobile</string>
        <key>AssociatedDomains</key>
        <array>
            <string>authsrv:customerorg.okta.com</string>
        </array>
    </dict>
    <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>
<!-- Other required payload keys -->

Kandji example

Copy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>PayloadContent</key>
        <array>
            <dict>
                <key>OktaVerify.OrgUrl</key>
                <string>https://customerorg.okta.com</string>
                <key>OktaVerify.PasswordSyncClientID</key>
                <!-- replace YOUR_CLIENT_ID with your Desktop Password Sync app Client ID -->
                <string>YOUR_CLIENT_ID</string>
                <key>PlatformSSO.ProtocolVersion</key>
                <string>2.0</string>
                <!-- optional keys-->
                <key>OktaVerify.EnrollmentOptions</key>
                <string>SilentEnrollmentEnabled</string>
                <key>OktaVerify.ReportDiagnostics</key>
                <true/>
                <key>OktaVerify.UserPrincipalName</key>
                <string>username@domain.com</string>
                <!-- optional keys-->
                <key>PayloadDescription</key>
                <string>Configures Okta Verify settings</string>
                <key>PayloadDisplayName</key>
                <string>Okta Verify configuration</string>
                <key>PayloadIdentifier</key>
                <string>DEB5863A-E503-468C-A3DE-D90479F1E10A</string>
                <key>PayloadOrganization</key>
                <string>CUSTOMER NAME</string>
                <key>PayloadType</key>
                <string>com.okta.mobile</string>
                <key>PayloadUUID</key>
                <string>1D89FEA8-BAFE-42F5-9393-634BE23009D8</string>
                <key>PayloadVersion</key>
                <integer>1</integer>
            </dict>
            <dict>
                <key>OktaVerify.OrgUrl</key>
                <string>https://customerorg.okta.com</string>
                <key>OktaVerify.PasswordSyncClientID</key>
                <!-- replace YOUR_CLIENT_ID with your Desktop Password Sync app Client ID -->
                <string>YOUR_CLIENT_ID</string>
                <!-- optional keys-->
                <key>OktaVerify.EnrollmentOptions</key>
                <string>SilentEnrollmentEnabled</string>
                <key>OktaVerify.ReportDiagnostics</key>
                <true/>
                <key>OktaVerify.UserPrincipalName</key>
                <string>username@domain.com</string>
                <!-- optional keys-->
                <key>PayloadDescription</key>
                <string>Configures Okta Verify settings</string>
                <key>PayloadDisplayName</key>
                <string>Okta Verify (auth service) configuration</string>
                <key>PayloadIdentifier</key>
                <string>E5F1356E-3B04-43F7-8E8C-2213F7D74B13</string>
                <key>PayloadOrganization</key>
                <string>CUSTOMER NAME</string>
                <key>PayloadType</key>
                <string>com.okta.mobile.auth-service-extension</string>
                <key>PayloadUUID</key>
                <string>6764E8E4-0A37-4206-96E2-A73B2DFA5673</string>
                <key>PayloadVersion</key>
                <integer>1</integer>
            </dict>
        </array>
        <key>PayloadDescription</key>
        <string>Configures settings</string>
        <key>PayloadDisplayName</key>
        <string>Okta Verify Configuration</string>
        <key>PayloadIdentifier</key>
        <string>com.customer-name.profiles.oktaverify</string>
        <key>PayloadOrganization</key>
        <string>CUSTOMER NAME</string>
        <key>PayloadScope</key>
        <string>System</string>
        <key>PayloadType</key>
        <string>Configuration</string>
        <key>PayloadUUID</key>
        <string>9A641D93-471C-44D7-8B54-264E842A12C8</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
    </dict>
</plist>

Configure custom preference files

These payload files, often referred to as the Managed app configurations, delivers your specific Okta settings to the Okta Verify app for macOS.

For Platform SSO to function, you need to create and deploy a preference file for each of the following preference domains:

com.okta.mobile
com.okta.mobile.auth-service-extension
com.okta.deviceaccess.servicedaemon: Optional. Only required for Device-Bound SSO.
com.apple.preference.security: Optional. Only required to block password reset.

com.okta.mobile

Create and save a text file named com.okta.mobile with the following contents. If this file has already been configured for Okta Verify or Okta FastPass, you don't need to recreate it for Platform SSO.

Copy

<key>PayloadType</key>
<string>com.okta.mobile</string>
<key>OktaVerify.OrgUrl</key>
<string>https://customerorg.okta.com</string>
<key>OktaVerify.UserPrincipalName</key>
<string>$USERNAME</string>

Replace the following items with your specific org configuration:

https://customerorg.okta.com is the URL for your Okta org.
$USERNAME is an optional value that's populated with the Okta username when the user registers for PSSO. If you don't specify a value, users have to enter their username when they sign in.

com.okta.mobile.auth-service-extension

Create and save a text file named com.okta.mobile.auth-service-extension with the following contents.

Copy

<key>PayloadType</key>
<string>com.okta.mobile.auth-service-extension</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</string>
<key>PlatformSSO.ProtocolVersion</key>
<string>2.0</string>

Replace the following items with your specific org configuration:

https://customerorg.okta.com is the URL for your Okta org.
$USERNAME is an optional value that's populated with the Okta username when the user registers for PSSO. If you don't specify a value, users have to enter their username when they sign in.
your-client-ID is the Client ID that you copied during the Platform SSO app creation.

You can retrieve this value from the Authentication tab of the configured Platform Single Sign-on app for macOS.

com.okta.deviceaccess.servicedaemon

Create and save a text file named com.okta.deviceaccess.servicedaemon with the following contents.

Copy

<key>PayloadType</key>
<string>com.okta.deviceaccess.servicedaemon</string>
<key>OktaJoinEnabled</key>
<true/>

This profile file is optional and is used for Device-Bound SSO. See Deploy Device-Bound SSO to user devices.

com.apple.preference.security

This profile disables the ability to change the local account password.

As the password is synced with Okta, users shouldn't change their password locally. To change a password, users should change their Okta password and then sync it at the lock screen of the computer. See Apple Security Preferences documentation.

Create and save a text file named com.apple.preference.security with the following contents.

Copy

<key>PayloadType</key>
<string>com.apple.preference.security</string>
<key>dontAllowPasswordResetUI</key>
<true/>

Here's an example com.apple.preference.security configuration file for Kandji:

Copy

<plist version="1.0">
    <dict>
        <key>PayloadContent</key>
        <array>
            <dict>
                <key>dontAllowPasswordResetUI</key>
                <true/>
                <key>PayloadIdentifier</key>
                <string>com.customer-name.profiles.dontAllowPasswordResetUI</string>
                <key>PayloadType</key>
                <string>com.apple.preference.security</string>
                <key>PayloadUUID</key>
                <string>d99bb019-1010-447f-8fed-8f223cc56be3</string>
                <key>PayloadVersion</key>
                <integer>1</integer>
            </dict>
        </array>
        <key>PayloadDisplayName</key>
        <string>Restrict Local Password Reset for Okta PSSO extension</string>
        <key>PayloadIdentifier</key>
        <string>com.customer-name.restrictLocalPasswordReset</string>
        <key>PayloadType</key>
        <string>Configuration</string>
        <key>PayloadUUID</key>
        <string>b44b6a04-6527-4333-1010-46422e8a5844</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
    </dict>
</plist>

Deploy and verify the profile

Use your MDM software to distribute the profile to all computers in scope, or to distribute only to newly assigned devices.

After you create and distribute the device management profile, your managed users can sync their local macOS password with their Okta password. Users receive a system notification message that registration is required to sync the two passwords.

Desktop Password Sync also sets up Okta FastPass as part of the enrollment process. Users may already have Okta FastPass enabled. If biometrics for Okta FastPass are enabled, the Desktop Password Sync enrollment flow prompts users for Touch ID to successfully set up Okta FastPass.

To verify the profile deployment on a macOS device:

Open the System Settings app.
Go to Device ManagementProfiles.
Confirm that you see device management profiles for each of your preference domains.

Deploy Okta Verify

Finally, use your MDM software to deploy the Okta Verify app to your enrolled macOS devices.

Next step

Support your macOS users