Platform Single Sign-on for macOS

Overview

Platform Single Sign-on (Platform SSO) lets you—or an identity management developer—build SSO extensions that allow users to authenticate with your organization’s identity provider (IdP) account on a Mac during Setup Assistant. Platform SSO can be combined with other SSO extensions with the following considerations:

• A specific domain can 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:

• Activate and enforce Platform SSO during Automated Device Enrollment to authenticate the enrollment, sign in with a Managed Apple Account, and create a local user.

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

• View Platform SSO status and registration details in System Settings.

• Synchronize passwords of local user accounts with the IdP, and define login policies.

• Define group permissions of IdP accounts and allow people to use network-only IdP accounts at authorization prompts.

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

• 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).

To maintain a trusted connection with the IdP independent of the user, Platform SSO supports shared device keys. Use shared device keys whenever possible—they’re required for Automated Device Enrollment, on-demand account creation, network authorization, and Authenticated Guest Mode

After the device registers successfully, the user registers as well, unless the account uses Authenticated Guest Mode. If the IdP requires it, the user may be prompted to confirm their registration. For on-demand local accounts, Platform SSO registers the user automatically in the background.

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 a local password or an IdP 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 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.

Some features, such as on-demand account creation, require 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

Organizations can activate and enforce Platform SSO during Setup Assistant with Automated Device Enrollment. This option works best for single-user devices. macOS automatically creates a local account for the user who authenticates enrollment, giving them immediate SSO access to supported native and web apps.

If configured, macOS downloads and installs the Platform SSO extension and configuration. This can occur prior performing the actual enrollment with the device management service which allows authenticating the enrollment with SSO or after the enrollment when the Mac is kept in the await configuration state. During this flow the Mac performs a device registration either silently or by prompting the user and asks the user to authenticate with their IdP to do the user registration. Users can’t proceed without successful Platform SSO registration.

After a successful authentication, macOS creates a local account, and the password either syncs with the IdP, or the user sets a local password (when Platform SSO uses a Secure Enclave–backed key). If necessary, you can enforce password complexity requirements for the local password using the Passcode configuration.

If configured, macOS can then sync the local account login profile picture from the IdP.

You can use Platform SSO during Automated Device Enrollment with an enforced software update. In this case, the device management service needs to enforce the update first.

If the user account that macOS creates is the only one on the Mac, it becomes an 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 group management.

Single Sign-on

Because Platform SSO is part of Extensible SSO, users log in once and use that authentication token to access supported native and web apps.

If tokens are missing, expired, or more than four hours old, Platform SSO attempts to refresh them or retrieve new ones from the IdP. You can also configure how long (minimum one hour, in seconds) before Platform SSO requires a full login instead of a token refresh. The default is 18 hours.

Platform SSO in System Settings

After registering with Platform SSO, users can check their registration status in System Settings > Users & Groups > [user name]. From there, they can repair the registration or refresh their authentication token.

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

Password synchronization and login policies

If you use the password authentication method, 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.

By default, the local account password is required to unlock FileVault, the Lock Screen, and the login window. If the entered password doesn’t match the password of the local user account, macOS attempts to reach the IdP to perform a live authentication. If macOS is unable to reach the IdP or the entered password doesn’t match the password stored by the IdP, 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, Lock Screen, and the login window:

• Attempt authentication.

  • If configured, there’s an attempt at live authentication with the IdP.

  • If the Mac is online, a successful authentication with the IdP is required to proceed, even when the Mac is 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 configured, live authentication with the IdP is required to proceed.

  • If the Mac is online, a successful authentication with the IdP is required 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 amount of days after a previous successful login, during which time the user can continue to use the local account password.

  • You can define if any account logging in to the Mac needs to be managed by Platform SSO or whether local-only accounts are still permitted. You can also set a grace period (in days) after the policy is applied before enforcement begins. This allows the temporary use of local accounts. For example, you can temporarily use an administrator account created by the device management service 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.

If necessary, local accounts (as defined by you) can be exempt from login policies and not prompted to register for Platform SSO.

Group management and network authorization

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.

Network authorization

Platform SSO allows users without a local Mac account to use their IdP credentials for authorization. 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.

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.

• Add the following: an SSO extension configuration with Platform SSO, shared device keys, and the option to create a user at login.

• Complete Setup Assistant and create a local administrator account.

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

Using an optional configuration, you can specify which IdP attribute to use for the local account name (short name) and full name. Administrators can also set the key for the account name to com.apple.PlatformSSO.AccountShortName to use the UPN prefix.

Additionally, you can define what privileges to apply to newly created accounts at login. The same options for group 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 group management.

The requirements are the same as on-demand account creation, except you configure Authenticated Guest Mode instead of the option to create a user at login.

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 macOS. 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.

User credentials are provisioned as access keys in an Apple Wallet pass through an iPhone app or browser. These access keys are stored in the device’s Secure Enclave, making them hardware-backed, and encrypted, and helping to protect from tampering or extraction attempts. Express Mode enables immediate authentication without requiring users to wake or unlock 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.