Extensible SSO declarative configuration for Apple devices

Use the Extensible SSO configuration to set up an app extension that performs single sign-on (SSO) across apps and websites. The extension can handle credential-based authentication for a set of hosts, or redirect-based authentication for a set of identity provider URLs. On Mac, this configuration also sets up Platform SSO, which lets people sign in to their Mac and unlock it using their identity provider account.

The Extensible SSO configuration supports the following:

Minimum supported operating system versions and channels: iOS 27, iPadOS 27, Shared iPad user, macOS 27 device, macOS 27 user, visionOS 27.
Requires supervision: No.
Supported enrollment methods: User Enrollment, Device Enrollment, Automated Device Enrollment.

Extensible SSO settings

Setting	Description	Required
Extension composed identifier	The identifier of the app extension that provides single sign-on. In iOS, iPadOS, and visionOS, use the app extension’s bundle ID (for example, `com.melardclothing.app.sso-extension`). In macOS, use a composed identifier in the format Bundle-ID (`Team-ID`); the bundle identifier followed by the Team ID from the app extension’s code signature (for example, `com.melardclothing.app.sso-extension (ABCD1234)`).	Yes
Type	The type of single sign-on the extension performs: Credential based or redirect for modern authentication methods.	Yes
Realm	The realm name for credential payloads. Enter the value with the correct capitalization. The operating system ignores this setting for redirect payloads.	No
Extension data	A dictionary of additional keys and values that the operating system passes through to the app extension. Use the keys and values the extension expects.	No
URLs	A list of URL prefixes for identity providers where the app extension performs single sign-on. Required for redirect payloads, and ignored for credential payloads. Each URL needs to begin with `http://` or `https://`. The operating system matches the scheme and hostname without regard to case, doesn’t allow query parameters or URL fragments, and requires that the URLs are unique across all installed Extensible SSO payloads.	No
Hosts	A list of host or domain names that apps can authenticate through the app extension. Required for credential payloads, and ignored for redirect payloads. The operating system matches host or domain names without regard to case and requires that they’re unique across all installed Extensible SSO payloads. A hostname that begins with a period is a wildcard suffix that matches all subdomains; any other hostname needs to match exactly.	No
Denied bundle identifiers	A list of bundle identifiers for apps that don’t use Single Sign-on provided by this extension.	No
Screen Lock behavior	The behavior for authentication requests while the screen is locked. The operating system can either cancel the request or continue without single sign-on. This setting doesn’t apply to requests where the user interface is turned off, or to background URL session requests.	No
Platform SSO	The settings that configure Platform SSO, which lets people sign in to and unlock a Mac using their identity provider (IdP) account. See the Platform SSO settings.	No

Platform SSO settings

Setting	Description	Required
Authentication method	The Platform SSO authentication method to use with the extension.	The SSO extension also needs to support the method.
Registration token	The token the device uses for silent registration with the IdP.	No
Use shared device keys	If turned on, the operating system uses the same signing and encryption keys for all users.	No
Login frequency	The duration, in seconds, until the operating system requires a full login instead of a token refresh. The default value is `64,800` (18 hours), and the minimum value is `3600` (1 hour).	No
Allow device identifiers in attestation	If turned on, the operating system includes the device UDID and serial number in Platform SSO attestations.	No
Account	The display and profile settings for the account. See the Account settings.	No
User creation	The settings for creating new local accounts through Platform SSO. See the User creation settings.	No
Authorization	The settings for authorization prompts and group membership. See the Authorization settings.	No
Access key	The settings for access key authentication. See the Access key settings.	No
Policies	The policies for login, unlock, and FileVault behavior. See the Policies settings.	No
Web authentication	The settings for web authentication behavior. See the Web authentication settings.	No

Account settings

Setting			Description						Required
Display name			The display name for the account in notifications and authentication requests.						No
Synchronize profile picture			If turned on, the operating system requests the user’s profile picture from the SSO extension.						No

User creation settings

Setting	Description	Required
Enable at login	If turned on, people can create accounts at the login window when the authentication method is Password or smart card.	Use shared device keys also needs to be turned on.
Enable first user during setup	If turned on, the device uses Platform SSO to create the first user account on the Mac during Setup Assistant.	No
Enable registration during setup	If turned on, the operating system turns on Platform SSO registration during Setup Assistant. Use this key when you configure Platform SSO before enrollment.	No
New user authentication methods	A list of authentication methods for newly created accounts at login or during Setup Assistant. The operating system uses Password and smart card SmartCard if this setting isn’t present.	No
New user authorization mode	The permission to apply to newly created accounts at login. Possible values are standard user, administrators, groups, and temporary for Authenticated Guest Mode.	No
Token to user mapping	The mapping of token claims to account attributes for creating users or for authorization. See the Token to user mapping settings.	No
Temporary session quick login	If turned on, the Mac uses a faster Authenticated Guest Mode login. The operating system erases user data from only select locations in the home directory after each session, and erases the full home directory once every eight hours. Turn this on for shared environments with a high frequency of short sessions.	No

Token to user mapping settings

Setting			Description						Required
Account name			The claim name to use for the user’s account name.						No
Full name			The claim name to use for the user’s full name.						No

Authorization settings

Setting	Description	Required
IdP accounts	If turned on, people can use IdP accounts at authorization prompts, and the operating system assigns groups using the administrator groups, additional groups, or authorization groups settings.	Use shared device keys also needs to be turned on.
User authorization mode	The permission to apply to an account each time the user authenticates. Possible values are standard user, administrators, and groups.	No
Administrator groups	A list of groups to use for administrator access. The operating system requests membership during authentication.	No
Additional groups	A list of groups that don’t have administrator access.	No
Authorization groups	A dictionary that pairs authorization rights with group names. Each key is an authorization right, and its value is the group to associate with that right. When you use this setting, the operating system updates the authorization right to use the group.	No

Access key settings

Setting	Description	Required
Reader group identifier	The reader group identifier for the access key. This value needs to match the configured access key.	If the new user authentication methods include access key.
Terminal identity asset reference	The identifier of an asset declaration that contains the identity to use as the terminal identity of the access key. The access key needs to trust the identity. Accepts an identity, ACME, or SCEP credential asset.	If the new user authentication methods include access key.
Reader issuer certificate asset reference	The identifier of an asset declaration that contains the issuer certificate for the terminal identity of the access key (also called the reader CA public key). The key needs to be an elliptic curve key. The issuer of the terminal identity needs to match this certificate, or authentication fails.	If the new user authentication methods include access key.
Allow Express Mode	If turned on, the operating system uses the access key in express mode and doesn’t require authentication before use.	No

Policies settings

Setting	Description	Required
FileVault	A list of policies to apply when using Platform SSO at FileVault unlock on a Mac with Apple silicon.	No
Login	A list of policies to apply when using Platform SSO at the login window.	No
Unlock	A list of policies to apply when using Platform SSO at screen saver unlock.	No
Offline grace period	The time, in seconds, after the last successful Platform SSO login during which people can use a local account password offline.	If the offline grace period policy is set.
Authentication grace period	The time, in seconds, after receiving or updating a FileVault, login, or unlock policy during which the operating system can use unregistered local accounts.	If the authentication grace period policy is set.
Non-platform SSO accounts	A list of local account user names that aren’t subject to the FileVault, login, or unlock policies. These accounts don’t receive a prompt to register for Platform SSO.	No

Web authentication settings

Setting			Description						Required
URL allow list			A list of hosts that the operating system can load in the Platform SSO web view.						If the authentication method or the new user authentication methods is set to web-based authentication.
Allow password sync			If turned on, the operating system detects the password during web authentication and syncs it to the user’s local account password.						No

Note: Not all configurations and their settings are available in all device management services. Each device management service developer implements these settings differently. To learn which settings are available for your devices, consult your developer’s device management service documentation.

Helpful?

Apple Platform Deployment