Platform Single Sign-on for macOS

Overview

Platform Single Sign-on (Platform SSO), available in macOS provides a seamless login and authentication experience to users. With Platform SSO, users can use their organizational identity throughout macOS starting with the initial setup instead of having to repeatedly interact with authentication prompts. To use Platform SSO, you need to deploy an SSO extension compatible with your identity provider (IdP) who implements the Platform SSO framework.

Platform SSO can be combined with other SSO extensions with the following considerations:

• A specific domain needs to be handled only by a single SSO extension.

• syncLocalPassword needs to be set to FALSE in the Kerberos SSO configuration.

Features

Platform SSO supports the following features:

• Provide a Single Sign-on experience for native and web apps.

• Use multiple authentication methods including password, Secure Enclave-backed keys, access keys, and smart cards.

• Activate and enforce Platform SSO during Automated Device Enrollment to authenticate the enrollment and create a local user account.

• Create additional local user accounts on demand when a user logs in with credentials from an IdP account.

• Synchronize IdP passwords with local user accounts.

• Get information about the status of Platform SSO and repair options in System Settings.

• Use login policies to define when to perform live password authentication with the IdP.

• Define privileges of IdP accounts and allow users to use network-only IdP accounts at authorization prompts.

• Support guest users who log in temporarily with their IdP credentials on shared Mac computers.

Requirements

• A Mac with Apple silicon or an Intel-based Mac with Touch ID

• A device management service that supports the Extensible Single Sign-on configuration, which includes settings for Platform SSO

• An app containing a Platform SSO extension compatible with the IdP

• macOS 13 or later

The following features have additional version requirements:

Set up Platform SSO

To use Platform SSO, the Mac and each user needs to register with the IdP. Depending on IdP support and the applied configuration, the Mac can perform device registration silently in the background using:

• A registration token of the IdP provided in the extensible SSO configuration

• An attestation, which provides a strong assurance that the Mac is a genuine Apple device and can optionally include device identifiers (UDID and serial number).

After the device successfully registers, the user then registers. If the IdP requires it, Platform SSO prompts the user to confirm their registration. How Platform SSO handles registration varies by account type:

• With prior device authentication: If device registration already involved user authentication and the SSO extension provided the necessary information and tokens, Platform SSO performs user registration in the background.

• On-demand local accounts: Platform SSO attempts user registration silently in the background. If that fails, it prompts the user.

• Authenticated Guest Mode accounts: Platform SSO skips user registration entirely for temporary accounts that Authenticated Guest Mode creates.

If necessary, local accounts (as defined by you) can be exempt from Platform SSO and aren’t prompted to register for Platform SSO. This also excludes them from features like login policies or requiring Touch ID.

Shared device keys

To maintain a trusted connection with the IdP independent of the user, Platform SSO supports shared device keys. Use shared device keys whenever possible as they are required for:

• Platform SSO during Automated Device Enrollment

• On-demand account creation

• Network authorization

• Authenticated Guest Mode

Authentication methods

Platform SSO supports different authentication methods with an IdP. Support for each depends on the IdP and the Platform SSO extension.

• Password: With this method, a user authenticates with the IdP using a password. It also supports WS-Trust, which allows the user to authenticate even when the IdP managing their account is federated.

• Secure Enclave–backed key: With this method, a user who logs in to their Mac with a local account password can use a Secure Enclave–backed key to authenticate with the IdP without a password. The IdP sets up the Secure Enclave key during the user registration process.

• Smart card: With this method, a user authenticates with the IdP using a smart card. To use this method, you need to:

  • Register the smart card with the IdP.

  • Configure smart card attribute mapping on the Mac.

    For details and an example attribute mapping configuration, see the man page for Smart Card Services project.

• Access key: With this method, users use a pass stored in Apple Wallet to authenticate with the IdP. Similar to a smart card, the access key needs to be registered with the IdP.

Certain functionalities require you to use a specific authentication method:

Feature				Password		Secure Enclave–backed key		Smart card		Access key
Group management
Automated Device Enrollment
Authenticated Guest Mode
On-demand account creation
Password synchronization

Platform SSO with Automated Device Enrollment

You can activate and enforce Platform SSO during Setup Assistant with Automated Device Enrollment. This works well for single-user Mac computers because macOS automatically creates a local account for the user who authenticates the enrollment, and that user can immediately use SSO with supported native and web apps.

When you configure Platform SSO with Automated Device Enrollment, macOS downloads and installs the Platform SSO extension and configuration. This can happen at two points:

• Before macOS enrolls with the device management service: Allows the user to authenticate enrollment with SSO.

• After enrollment: When the device management service holds macOS in the awaiting configuration state.

During this flow, macOS performs device registration either silently or by prompting the user. If macOS performs silent device registration, or if Platform SSO didn’t receive the necessary user information and tokens, the user must authenticate with their IdP to complete user registration. This also establishes a user identity in macOS. Users can’t proceed without successful Platform SSO registration.

After the user authenticates successfully, macOS creates a local user account. Using an optional configuration key, you can define which attribute from the IdP to use for the local user account name (often called the user’s short name) and full name. Device management service administrators can also set the key for the account name to com.apple.PlatformSSO.AccountShortName to use the UPN prefix.

The password either syncs with the IdP if user registration was done with password, or the user sets a local password. If necessary, you can enforce password complexity requirements for the local password using the Passcode configuration.

When you configure it, macOS can then sync the local account’s login profile picture from the IdP.

If the user account macOS creates is the only account on the Mac, that account becomes a local administrator account. If the device management service created an administrator account using the account configuration command, you can assign the user account different privileges using Platform SSO privilege management.

Single Sign-on

Because Platform SSO is part of Extensible SSO, it provides the same Single Sign-on capabilities and allows users to log in once, then use the token from the initial authentication to authenticate with supported native and web apps.

If tokens are missing, expired, or more than four hours old, Platform SSO attempts to refresh or retrieve new ones from the IdP. Additionally, you can configure a duration in seconds (minimum one hour) until Platform SSO requires a full login instead of a token refresh. A full login may prompt the user to act. For example, to present their smart card or use Touch ID (if the Platform SSO extension requires biometric authentication). By default, Platform SSO requires a full login every 18 hours.

Platform SSO in System Settings

User registration

After the device registers Platform SSO, users can inspect their registration status in System Settings > Users & Groups > [user name]. If necessary, they can repair the registration and force a refresh of their authentication token.

Device registration

The device registration status is visible in Users & Groups > Network account server and also provides an option to perform a repair.

Password synchronization

If you use password authentication, the local user password automatically syncs with the IdP whenever a user changes their password, either locally or remotely. If necessary, macOS prompts the user for their previous password.

Login policies

By default, macOS requires the local account password to unlock FileVault, the Lock Screen, and at the login window. If the entered password doesn’t match the password of the local user account, macOS attempts to reach the IdP to authenticate the user live. If macOS can’t reach the IdP, or the entered password doesn’t match the password the IdP stores, authentication fails.

With login policies, you can allow the use of the current account password from the IdP at these three prompts immediately. You can also set the following policies individually for FileVault, the Lock Screen, and the login window:

• Attempt authentication.

  • If you configure this policy, macOS attempts to authenticate the user live with the IdP.

  • If the Mac is online, the user needs to authenticate successfully with the IdP to proceed, even if the Mac goes offline after the first attempt.

    If authentication is successful, Platform SSO updates the local password.

  • If the Mac is offline, the user can use their local account password.

• Require authentication.

  • If you configure this policy, the user needs to authenticate live with the IdP to proceed.

  • If the Mac is online, the user needs to authenticate successfully with the IdP to proceed, regardless of a configured offline grace period.

    If authentication is successful, Platform SSO updates the local password.

  • If the Mac is offline, users can’t log in. In those situations, you can enable an offline grace period and set it to the number of days after a previous successful login, during which time the user can continue to use the local account password.

  • You can define whether any account logging in to the Mac needs to be managed by Platform SSO, or whether macOS still allows login with local-only accounts. You can also define the number of days after Platform SSO applies or updates the policy before macOS enforces this setting. This temporarily allows users to use of local accounts. For example, you can temporarily use an administrator account that the device management service created to perform or repair the Platform SSO device registration.

  • Instead of live authentication, you can also allow users to use Touch ID or Apple Watch on the Lock Screen.

Recovery scenarios

When live authentication with the IdP is required but the Mac can’t perform it, users are unable to log in. In those situations, the following options may help users regain access:

• If the user is unable to unlock FileVault, they can enter a Personal Recovery Key by pressing Option + Shift + Return to reach the login window. When macOS connects to a network at the login window, a device management service can deploy an updated configuration. For example, you could temporarily remove the login policy to allow the user to log in with the local account password.

• As a last resort, if macOS can’t connect to a network to receive an updated configuration, recoveryOS provides a bypass option. To use this option, the user needs the FileVault Personal Recovery Key and—if configured—the Recovery Lock password. After the user is in recoveryOS, the security platformsso bypass-login-policy command temporarily removes the requirement to authenticate live. The bypass lasts for 12 hours or until a successful authentication with the IdP is performed.

Privilege management

Platform SSO can provide granular rights management by applying the following privileges to an account each time the user authenticates:

• Standard: The account gets standard user privileges.

• Administrator: Adds the account to the local administrator group.

• Groups: Define privileges by group membership, which update every time the user authenticates with the IdP.

When you use groups, an account gets privileges based on membership of the following:

• Administrator groups: If the account is part of a listed group, they have local administrator access.

• Authorization groups: If the account is part of a group assigned to a built-in or custom-defined authorization right, then the account has privileges associated with that group. For example, macOS uses the following authorization rights:

  • system.preferences.datetime, which allows the account to modify time settings.

  • system.preferences.energysaver, which allows the account to modify energy saver settings.

  • system.preferences.network, which allows the account to modify network settings.

  • system.preferences.printing, which allows the account to add or remove printers.

• Additional groups: Custom-defined groups for macOS or specific apps, which macOS creates automatically inside the local directory (if they don’t already exist). For example, you can use an additional group in the sudo configuration to define sudo access. Users are mapped to those groups after authentication with the IdP.

Network authorization

Platform SSO expands the use of IdP credentials for authorization purposes to users who don’t have a local account on the Mac. These accounts use the same groups as group management. For example, if the account is a member of one of the administrator groups, it can perform administrator authorization prompts. To use this functionality, configure Platform SSO with shared device keys.

Network authorization isn’t possible with authorization prompts that require a secure token, ownership permissions, or authentication by the current logged-in user.

On-demand account creation

In shared deployments, users can log in with their IdP user name and password or a smart card to automatically create a local account. This is especially useful if the same users return to a Mac, like shift-workers or classroom setups where students use the same Mac throughout a school year.

You can achieve a fully automated provisioning process using Automated Device Enrollment with Auto Advance. You need to create the first local administrator account using a device management service, and perform silent Platform SSO registration.

The following are required to use on-demand account creation:

• Enroll the Mac in a device management service that supports bootstrap tokens.

• Complete Setup Assistant and create a local administrator account.

• Have the Mac at the login window with FileVault unlocked and a network connection.

This is also applicable for Platform SSO with Automated Device Enrollment where you can use an optional configuration key to define which attribute from the IdP to use for the local user account name.

Additionally, you can define what privileges to apply to newly created accounts at login. The same options as for privilege management are available:

• Standard: The account gets standard user privileges.

• Administrator: Adds the account to the local administrator group.

• Groups: Define privileges by group membership, which update every time the user authenticates with the IdP.

Authenticated Guest Mode

Authenticated Guest Mode provides a streamlined login experience for shared deployments, such as medical offices or schools, where users sign in temporarily with their IdP credentials and don’t need a persistent local account. The user gets standard user privileges by default, but you can change those privileges using Platform SSO privilege management.

Authenticated Guest Mode can be used together with Platform SSO enabled local user accounts. This allows a primary user of the Mac to benefit from Platform SSO capabilities while others can log in temporarily if needed.

To use this feature, the following requirements apply:

• Enroll the Mac in a device management service that supports bootstrap tokens.

• Complete Setup Assistant and create a local administrator account.

When a user logs out, macOS erases all local data for that account, and the shared Mac is ready for the next user to log in.

Tap to Login

Tap to Login brings Apple Wallet digital credential support to the Mac. Organizations that already use digital badges in Apple Wallet (letting users unlock doors with an iPhone or Apple Watch) can now extend that same experience to Mac login.

This authentication method is particularly valuable for organizations that share a Mac across multiple users, including educational institutions, retail environments, and healthcare facilities.

With Tap to Login, users can authenticate on a Mac configured for Authenticated Guest Mode when they tap their iPhone or Apple Watch on an attached NFC reader. This initiates a secure single sign-on process that automatically authenticates users to their apps and websites, allowing them to quickly log in and get to work.

An iPhone or iPad app or browser provisions user credentials as access keys in an Apple Wallet pass. The device’s Secure Element stores these access keys, making them hardware-backed and encrypted, and helps protecting them from tampering or extraction. Express Mode enhances convenience by letting users authenticate immediately without waking or unlocking their device, similar to how transit cards work in Apple Wallet.

To implement Tap to Login functionality, the Mac needs to be:

• Configured for Authenticated Guest Mode

• Equipped with a supported external NFC reader

Access key creation and management requires participation in the Apple Wallet Access Program. For more information on how to create an access key, see Provisioning in the Apple Wallet Access Program Guide.