Configure device configuration profiles for Secure Enclave using a generic MDM

Early Access release

This guide provides general instructions to configure the required device management profiles for Platform SSO with Secure Enclave-backed keys.

You can use any Mobile Device Management (MDM) solution that supports extensible single sign-on (SSO) payload deployment with Platform SSO authentication enabled.

For details about the benefits, prerequisites, and version compatibility of PSSO, see Platform SSO for macOS.

Start this task

This guide includes the steps required to configure Device-Bound Single Sign-On. This feature is required to use Secure Enclave–backed keys. Following these steps means no additional steps are needed for Device-Bound SSO.

To enable the full functionality, you need to create and deploy three types of configuration profiles:

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 Platform SSO. 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.

When asked to provide your org's URL in this guide, for example, https://customerorg.okta.com, use your own Okta org address, and use the same org URL each time.

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

Configure the SSO extension profile

The SSO extension extends the macOS sign-in authentication into the user's session after they unlock their device. Users can use device-bound credentials to unlock and sign in to their computer.

Create an MDM profile with the following parameters:

Key	Value
Payload Type	SSO
Extension Identifier	com.okta.mobile.auth-service-extension
Team Identifier	B7F62B65BN
Type	Redirect
Authentication method	User Secure Enclave Key
Use Shared Device Keys	True (enabled)
Use Platform SSO	True (enabled)
Enable registration during setup	If you are using Platform SSO in Setup Assistant for macOS 26 Tahoe or later, 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 SSO extension profile example

Copy

<key>PayloadType</key>
<string>com.apple.extensiblesso</string>
<key>PlatformSSO</key>
<dict>
    <key>AccountDisplayName</key>
    <string>Company Name</string>
    <key>AuthenticationMethod</key>
    <string>UserSecureEnclaveKey</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>

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. See Apple's Associated Domains documentation.

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. See Apple's Associated Domains documentation.

Generic associated domains 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 -->

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. You can use the same configuration for Secure Enclave–backed keys.

Copy

<plist version="1.0">
<dict>
    <key>OktaVerify.OrgUrl</key>
    <string>https://customerorg.okta.com</string>
    <key>OktaVerify.UserPrincipalName</key>
    <string>$USERNAME</string>
    <key>PlatformSSO.ProtocolVersion</key>
    <string>2.0</string>
</dict>
</plist>

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 is 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

<plist version="1.0">
<dict>
    <key>OktaVerify.OrgUrl</key>
    <string>https://customerorg.okta.com</string>
    <key>OktaVerify.UserPrincipalName</key>
    <string>$USERNAME</string>
    <key>OktaVerify.PasswordSyncClientID</key>
    <string>your-client-ID</string>
    <key>PlatformSSO.ProtocolVersion</key>
    <string>2.0</string>
</dict>
</plist>

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 is 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

<plist version="1.0">
<dict>
    <key>OktaJoinEnabled</key>
    <true/>
</dict>
</plist>

This allows the device to be joined to Okta and use Device-Bound SSO. See Deploy Device-Bound SSO to user devices.

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, users receive a system notification message that registration is required.

Platform SSO with a Secure Enclave–backed key 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 Platform SSO 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