Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 22 Packages Projects Releases Wiki Activity

[Guide] Enhance guide with Simplified Platform SSO details (#45298)

Browse Source 
Added details on Simplified Platform SSO introduced in macOS 26,
including prerequisites, configuration steps, and user experience.

<!-- Add the related story/sub-task/bug number, like Resolves #123, or
remove if NA -->
**Related issue:** Resolves #30674
This commit is contained in:
melpike
2026-05-13 09:01:02 -06:00
committed by GitHub
parent 4c29a7aebc
commit b908589849
3 changed files with 90 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
articles/deploying-entra-platform-sso-with-fleet.md
+2
View File
@@ -3,6 +3,8 @@ Apple’s Platform Single Sign-on (Platform SSO), [introduced at WWDC22](https:/
This guide details how to deploy Microsoft Entra ID's macOS Platform SSO extension to your Fleet macOS hosts.
> Fleet is testing [Simplified Setup](https://support.apple.com/en-gb/guide/deployment/dep7bbb05313/web#:~:text=Activate%20and%20enforce%20Platform%20SSO%20during%20Automated%20Device%20Enrollment%20to%20authenticate%20the%20enrollment%2C%20sign%20in%20with%20a%20Managed%20Apple%20Account%2C%20and%20create%20a%20local%20user) with Entra ID, which is currently in "preview" status.
## Why use Platform SSO?
If your Identity Provider (IdP) supports Platform Single Sign-on, deploying it in your environment offers a great and secure sign-in experience for your users.
articles/deploying-okta-platform-sso-with-fleet.md
+80 -1
View File
@@ -2,7 +2,7 @@
Apple's Platform Single Sign-on (Platform SSO), [introduced at WWDC22](https://developer.apple.com/videos/play/wwdc2022/10045) alongside macOS Ventura, iOS 17, and iPadOS 17, enables users to sign in to their identity provider credentials once and automatically access apps and websites that require authentication through an IdP.
This guide details how to deploy Okta's macOS Platform SSO extension (Desktop Password Sync) to your Fleet macOS hosts.
This guide details how to deploy Okta's macOS Platform SSO extension (Desktop Password Sync) to your Fleet macOS hosts. It covers both the standard Platform SSO setup (macOS 13+) and the newer [Simplified Platform SSO](#simplified-platform-sso-macos-26) workflow introduced in macOS 26.
If your Identity Provider (IdP) supports Platform Single Sign-on, deploying it in your environment offers a great and secure sign-in experience for your users.
@@ -347,6 +347,73 @@ Once registration is complete, the user's local macOS password will sync with th
- Experience seamless authentication to Okta-protected apps in web browsers
- No longer need to enter passwords or complete MFA challenges for Okta-protected resources
## Simplified Platform SSO (macOS 26+)
Apple introduced Simplified Platform SSO in macOS 26. It streamlines the Platform SSO setup by presenting a **Single Sign-On for Mac** page during Setup Assistant, allowing users to authenticate with their IdP right out of the box with no post-enrollment registration step required.
### Prerequisites (Simplified Platform SSO)
In addition to the [standard prerequisites](#prerequisites) above, Simplified Platform SSO requires:
- Hosts running **macOS 26** or later
- Hosts enrolled via **Apple Business (AB)**
- Fleet's **Setup experience** configured for the target fleet
- The latest **Okta Verify** installer downloaded from your Okta tenant or via Fleet-maintained apps (not the App Store version)
### Step 1: Configure profiles
Simplified Platform SSO uses the same Extensible SSO / Platform SSO profile and Okta Device Access SCEP profile described in the sections above. Follow the existing instructions to create:
- An **Extensible Single Sign-On** profile with Platform SSO settings.
- View example **[Extensible Single Sign-On profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/okta-sso-extension-simplified-setup-example.mobileconfig)**
- An **Associated domains** profile.
- View example **[Associated domains profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/okta-associated-domains-example.mobileconfig)**
- An **Okta App configuration** profile. This profile includes IdP variables, if you don't have IdP authentication enabled for enrollment you can delete the key and value for `OktaVerify.UserPrincipalName`.
- View example **[Okta App configuration profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/okta-app-config-example.mobileconfig)**
- An **Okta Device Access SCEP** certificate profile.
- View example **[dynamic Okta Device Access SCEP profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/okta-device-access-scep-dynamic-example.mobileconfig)**
- View example **[static Okta Device Access SCEP profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/okta-device-access-scep-example.mobileconfig)**
> Extensible Single Sign-On, Associated domains, and Okta App configuration profiles can be combined into a single profile for simplicity.
Upload all profiles to the target fleet in Fleet under **Controls > OS Settings > Configuration profiles**.
For best results, don't use labels to scope Platform SSO profiles to ensure they're immediately applicable to hosts during setup.
### Step 2: Add Okta Verify as a setup experience app
Download the latest `OktaVerify-Installer.pkg` from your Fleet-maintined apps or Okta Admin Console (**Settings > Downloads**). Don't use the App Store version as it lacks the required MDM integration features.
If downloading from Okta Admin Console, in Fleet navigate to the target fleet and go to **Controls > Setup experience > Install software**. Upload the Okta Verify installer so that it is installed on the host during setup experience.
### Step 3: Enroll via AB
Enroll the host through Apple Business. After setup experience completes (profiles are delivered and Okta Verify is installed), the user is presented with a new **Single Sign-On for Mac** page containing an Okta login prompt.
### End user experience (Simplified Platform SSO)
1. **Single Sign-On for Mac screen:** After setup experience, the user sees an Okta login page. They enter their Okta credentials to authenticate.
2. **Create account screen:** After authenticating, the standard macOS create-account screen appears, but all fields are locked (the user can only edit the **password hint**). The local account password is automatically set to match their Okta password.
3. **Okta Verify setup:** Later in Setup Assistant, the user logs into Okta a second time to finalize the Okta Verify registration on the device.
### Password syncing behavior
With Simplified Platform SSO, the user's local macOS password is tied to their Okta password:
- Users **cannot** set a local password that differs from their Okta password.
- If the Okta password is changed via the Okta web UI, the user may not immediately receive a notification to sync. Locking the screen and unlocking with the **new** Okta password triggers the sync and the old password stops working at that point.
### Multiple credential prompts
When Fleet's **IdP authentication** is also enabled, the user enters IdP credentials **three times** during enrollment:
1. MDM enrollment IdP authentication
2. Platform SSO authentication (Single Sign-On for Mac screen)
3. Okta Verify setup
### Managing mixed macOS versions
If your fleet includes hosts running macOS versions older than macOS 26, carefully review Apple's Platform SSO documentation to understand which features are supported on each version. Consider assigning hosts on older macOS versions to a **separate fleet** in Fleet so they receive the standard Platform SSO profiles (described earlier in this guide) rather than the Simplified Platform SSO configuration.
## Troubleshooting
### Platform SSO 2.0 Considerations
@@ -361,10 +428,22 @@ To verify SCEP certificates were deployed correctly on macOS:
3. Confirm the client certificate and private key exist
4. Verify the certificate has a custom extension with OID `1.3.6.1.4.1.51150.13.1`
### Simplified Platform SSO: Okta Verify factor on a wiped device
If a user's only Okta Verify factor is registered on the host being set up, and that host is wiped and re-enrolled, the final Okta Verify setup step will fail. Okta's logs do not surface a clear error for this scenario.
**Fix:** Before re-enrolling a wiped device, revoke both the host and the user's Okta Verify registrations in the Okta Admin Console.
### Simplified Platform SSO: SCEP or Okta Verify install failure
If the Okta SCEP certificate enrollment fails or the Okta Verify installation fails during setup experience, the user gets stuck at the Single Sign-On for Mac screen with no clean way to proceed. Verify that the SCEP profile is correctly configured and that the Okta Verify package uploaded to Fleet is the latest version from your Okta tenant. Admins can wipe hosts from Fleet to retry the setup.
## Additional Resources
For more detailed information about configuring Okta Desktop Password Sync, see the [official Okta documentation](https://help.okta.com/oie/en-us/content/topics/oda/macos-pw-sync/configure-macos-password-sync.htm).
To see a full list of properites for the Extensible Single Sign-On configuration profile, see the [Apple documentation](https://developer.apple.com/documentation/devicemanagement/extensiblesinglesignon).
To create and customize configuration profiles, download [iMazing Profile Editor](https://imazing.com/profile-editor).
For Device Access SCEP certificate configuration details, see [Use Okta as a CA for Device Access](https://help.okta.com/oie/en-us/content/topics/oda/oda-as-scep-okta-ca.htm) and [Okta's Device Access certificates documentation](https://help.okta.com/oie/en-us/content/topics/oda/oda-as-scep.htm).
articles/setup-experience.md
+8
View File
@@ -36,6 +36,10 @@ You can enforce end user authentication during automatic enrollment (ADE) for Ap
> (SSO)](https://fleetdm.com/docs/deploy/single-sign-on-sso) in Fleet, you still want to create a
> new SAML app for end user authentication. This way, only Fleet users can log in to Fleet.
## Platform SSO
Fleet supports configuring Platform SSO (PSSO) for macOS hosts with the option to create a local user account during enrollment. If you use Okta, see [Deploying Okta Platform SSO with Fleet](https://fleetdm.com/guides/deploying-okta-platform-sso-with-fleet) for setup instructions. PSSO can be used with or without [end user authentication](#end-user-authentication) enabled.
## End user license agreement (EULA)
To require a EULA, in Fleet, head to **Settings > Integrations > MDM > End user license agreement (EULA)** or use the [Fleet API](https://fleetdm.com/docs/rest-api/rest-api#upload-an-eula-file).
@@ -63,8 +67,11 @@ The following are examples of what some organizations deploy using a bootstrap p
To add a bootstrap package to Fleet, we will do the following steps:
1. Download or generate a package
2. Sign the package
3. Upload the package to Fleet
4. Confirm package is uploaded
### Step 1: Download or generate a package
@@ -101,6 +108,7 @@ Verify that the package is a distribution package:
To sign the package we need a valid Developer ID Installer certificate:
1. Login to your [Apple Developer account](https://developer.apple.com/account).
2. Follow [Apple's instructions to create a Developer ID Installer certificate](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates).
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package.