Configuring Simplified Setup for Platform SSO using Jamf Pro and Okta

Updated
  • 7 minute(s) read
Prev Next

About Okta Platform Single Sign-on for macOS

Introduced in macOS 26, Simplified Setup is a new method to require Platform SSO (PSSO) registration during Automated Device Enrollment at Setup Assistant, which can also create the first local user account on macOS with just-in-time account creation.

With this feature, users must register with their identity provider before proceeding with device setup. The first user account is then created and governed by the user’s organizational identity provider (IdP).

Useful for:

  • 1:1 computer deployments

  • Enabling user-level MDM management for the identity-based user from Setup Assistant

  • Zero-touch provisioning and compliance enforcement

Instructions

Create and configure the platform single sign-on app in Okta

  1. Sign in to your Okta org as a super admin.

  2. Go to Applications > Applications > Catalog and Browse App Catalog. Search for Platform Single Sign-on for macOS.

  3. Click Add Integration.

    Note: this application will only be available for customers with Okta Device Access (ODA) licensing.

  4. Open Platform Single Sign-on from your Applications list.

    • On the General tab, you can edit the app label or use the default label.

    • On the Sign on tab, make note of the Client ID. This is needed for the managed app configuration for Okta Verify in your MDM deployment.

    • To use Desktop Password Sync, users must have the Platform Single Sign-on app assigned. Assign the app to individual users or groups on the Assignments tab.

  5. In Directory > Profile Editor in the Okta tenant, find the Platform Single Sign-On for macOS User.

  6. Add two new attributes:

    1. macOSAccountFullName

    2. macOSAccountUsername

    There should now be two custom attributes for the PSSO app to use.

  7. Back in the Platform Single Sign-On for macOS application in Okta, go to the Authentication tab and click the Configure profile mapping link.

  8. Select the Okta User to Platform Single Sign-On for macOS tab. The new custom attributes should be visible there.

  9. Configure the settings for whatever works best for your organization.

  10. Use the Preview button at the bottom to confirm that the attributes pull in as expected.

  11. Click Save Mappings.

Add Okta as a CA with dynamic SCEP challenge for macOS

  1. In the Okta admin portal navigate to Security > Device Integrations. Select Device Access, then Add SCEP Configuration.

  2. Select Dynamic SCEP URL, then Generate.

  3. Note the SCEP URL, Challenge URL, Username, and Password. Those will be needed to make the deployable configuration in Jamf Pro.

  4. Click Save.

Creating the Platform SSO profile for deployment in Jamf Pro

  1. Navigate to Computers > Configuration Profiles and create a new profile for deployment.

  2. Set a Name, Description, and Category. Deploy at the Computer Level, and set distribution to Install automatically.

  3. Find the Single Sign-On Extensions payload and click Add.

    • Payload type: SSO

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

    • Team Identifier: B7F62B65BN

    • Sign-on Type: Redirect

    • URLs (use the Add button to generate a second field for entry)

      • https://<org-tenant>.okta.com/device-access/api/v1/nonce

      • https://<org-tenant>.okta.com/oauth2/v1/token

  4. Continue configuration in the Setting area of the Single Sign-On Extension payload (modify these values based on organizational preference, some examples are listed below):

    • Use Platform SSO: Include

      • Authentication method: Password

    • FileVault Policy (Apple silicon): Attempt & Include

    • User login policy: Attempt & Include

    • Screensaver unlock policy: Attempt & Include

    • Enable registration during setup: Enable & Include

    • Create first user during Setup: Enable & Include

      • New user creation authentication method: Password & Include

    • Use Shared Device Keys: Enable & Include

    • Account Display Name: Include (e.g., Company IT)

  5. Add three payloads under Application & Custom Settings > Upload.

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

      1. Property list example:

        <?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>OktaVerify.EnrollmentOptions</key>
<string>SilentEnrollmentEnabled</string>
<key>OktaVerify.OrgUrl</key>
<string>https://org-tenant-url.okta.com</string>
<key>OktaVerify.UserPrincipalName</key>
<string>$USERNAME</string>
<key>OktaVerify.PasswordSyncClientID</key>
<string>replace-with-PSSO-app-client-id</string>
<key>PlatformSSO.ProtocolVersion</key>
<string>2.0</string>
</dict>
</plist>

    2. com.okta.mobile

      1. Property list example:

        <?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>OktaVerify.EnrollmentOptions</key>
<string>SilentEnrollmentEnabled</string>
<key>OktaVerify.OrgUrl</key>
<string>https://org-tenant-url.okta.com</string>
<key>OktaVerify.UserPrincipalName</key>
<string>$USERNAME</string>
</dict>
</plist>

    3. com.apple.preference.security

      1. Property list example

        <?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>dontAllowPasswordResetUI</key>
<true/>
</dict>
</plist>

  6. Add your desired Scope for deployment (a section on creating and using a test scope is included later in this document).

  7. Click Save.

Create the SCEP configuration in Jamf Pro

  1. Navigate to Computers > Configuration Profiles and create a new profile for deployment.

  2. Set a Name, Description, and Category. Deploy at the Computer Level, and set distribution to Install automatically.

  3. Go to the SCEP payload and Configure.

  4. Configure as follows:

    1. URL: the SCEP URL provided while configuring the dynamic SCEP challenge in the Okta tenant

    2. Name: enter a name (e.g., CA-OKTA )

    3. Redistribute Profile: set a value based on organizational preference (e.g., 14 days)

    4. Subject: add a subject name template

      1. Note: Okta’s documentation notes that this field has a character limit and has suggestions for shorter names to ensure the profile can be effectively redistributed

      2. Example subject name:
        CN=$SERIALNUMBER ODA $PROFILE_IDENTIFIER

    5. Challenge Type: Dynamic-Microsoft CA

      1. URL to SCEP Admin: Enter the Challenge URL provided while configuring the dynamic SCEP challenge in the Okta tenant

      2. Username: Enter the Username provided while configuring the dynamic SCEP challenge in the Okta tenant

      3. Password: Enter the password provided while configuring the dynamic SCEP challenge in the Okta tenant

      4. Verify Password: re-enter the password

      5. Retries & Retry Delay can be left at 0.

      6. Certificate Expiration Notification Threshold should be set to organizational preference (e.g., 15 days).

      7. Key size: 2048

      8. ✅ Check Use as digital signature.

      9. ⬜️ Uncheck Allow export from keychain.

      10. ✅ Check Allow all apps access.

  5. Add your desired Scope for deployment (a section on creating and using a test scope is included later in this document).

  6. Click Save.

Create a PreStage Enrollment for Platform SSO in Jamf Pro

  1. In Jamf Pro navigate to Computers > PreStage Enrollments.

  2. Create a new PreStage Enrollment. Set organizationally-preferred options in the General section.

  3. Under Enrollment Requirements organizational requirements may vary. For Platform SSO during Setup Assistant check the Enable Simplified Setup for Platform Single Sign-on (macOS 26 or later) option to enable.

    1. Change the Minimum required macOS version to 26.0.

    2. Set the Platform Single Sign-on App Bundle ID to com.okta.mobile.

  4. Under Configuration Profiles ensure that the PSSO profile and SCEP profile are included.

  5. In Enrollment Packages include an Okta Verify installer (version 9.52 or later).

  6. Adjust any other settings as desired for the PreStage and click Save.

Making a limited testing scope

The following steps outline one way to create a test group for evaluating Platform SSO.

  1. Navigate to Computers > Smart Groups and create a new Smart Group.

  2. Give it a Name and Description (optional).

  3. For Criteria, select Show Advanced Criteria and select Enrollment Method: PreStage enrollment. Add the name of the test PreStage created above to the Value field and click Save.

  4. Add the new Smart Group as the scope for the PSSO configuration and SCEP configuration created above.

  5. Add test computers to the scope of the PreStage created above.

  6. Add the new Smart Group to the exclusion scope for any settings that may conflict with the testing PSSO configuration (e.g., Jamf Connect Login, previous Okta SCEP deployments).

  7. Add the new Smart Group to the exclusion scope for any policy deployments that may conflict with the testing PSSO configuration (e.g., Okta Verify deployments, Jamf Connect component installations).

Troubleshooting + Tips

Profile for debug log collection and troubleshooting

Apple has provided a set of instructions for a deployable profile to enable debug logging for advanced troubleshooting of Platform SSO. Instructions and profile download links are available on the Apple Developer site for customers with an Apple Developer Account.

Uploading the AppSSO.mobileconfig file from the Apple Developer site to Jamf Pro will create a signed Enterprise Single Sign-on Diagnostics profile that can be added to a PreStage and/or deployed to computers enrolled with Platform SSO. The additional debug details can be used for advanced troubleshooting and providing more verbose logging to Apple, IdPs, and/or MDM vendors for feedback and support purposes.

Manually enabling debug logging for PSSO at the desktop

Debug logging can also be enabled manually in Terminal.app at the desktop.

  1. Turn on debug mode:

    sudo log config --mode "level:debug,persist:debug" --subsystem "com.apple.AppSSO"

  2. Reproduce the issue if possible.

  3. Capture a sysdiagnose:
    sudo sysdiagnose

  4. Turn off debug when finished:
    sudo log config --reset --subsystem "com.apple.AppSSO"

Reviewing Okta Verify logs in Setup Assistant during Automated Device Enrollment

Open Terminal by pressing command+option+control+t on the keyboard during Setup Assistant.

Logs for Okta Verify are located at ~/Library/Group Containers/B7F62B65BN.group.okta.macverify.shared/Logs

Check PSSO status of logged-in user account

To review the PSSO status of a logged-in user account run app-sso platform -s in Terminal.app.

Unable to Sign-In during Automated Device Enrollment

If you encounter the following error message during enrollment:

The single sign-on extension could not validate the domain. Contact your administrator to help get single sign-on set up.

This message often indicates that the Associated Domains payload is not being recognized during device access registration with Okta. One way to validate this behavior is to edit the Platform SSO configuration profile and remove the entire Associated Domains payload, recreate it the payload, then redeploy the profile. Click Try Again and the process should continue on as expected.

Demo Video

Resources

🔗 Platform Single Sign-on for macOS (Apple)

🔗 Configure Desktop Password Sync for macOS 15 (Okta)

🔗 Desktop Password Sync for macOS (Okta)

🔗 Device Access certificates (Okta)

🔗 Use Okta as a CA for Device Access (Okta)

🔗 Just-In-Time Local Account Creation for macOS (Okta)

🔗 Add custom attributes to apps, directories, and identity providers (Okta)

🔗 Map Okta attributes to app attributes in the Profile Editor (Okta)