The Complete macOS SSO Playbook: Advanced Configuration Strategies Explained

Extending our previous insights from “Implementing Platform SSO for macOS: A Deep Dive into Configuration & Troubleshooting“

Platform SSO for macOS: A Deep Dive into Configuration & Troubleshooting

In our previous blog, we walked through the essentials of configuring Platform Single Sign-On (SSO) for macOS devices using Microsoft Intune. Today, let’s take a step further into the technical details—exploring advanced configuration keys, reviewing sample logs, and discussing developer best practices to help you fine-tune your environment.

Overview of Platform SSO for macOS

Platform Single Sign-On (SSO) for macOS is a robust framework designed to streamline and secure the authentication process on Apple devices. It enables users to seamlessly sign into their macOS devices and associated applications using their identity provider (IdP) credentials—such as those from Microsoft Entra ID—while maintaining the stringent security requirements inherent to macOS.

Key Features and Benefits

Broad OS Support:
Extensible SSO is available on macOS starting from version 10.15, with advanced capabilities and additional keys introduced in later versions (e.g., macOS 13 and macOS 15). This wide compatibility ensures that both older and newer macOS devices can benefit from a unified SSO solution.

Seamless Integration:
Platform SSO allows users to authenticate with a single set of credentials across local macOS accounts and cloud-based services. By synchronizing local account attributes with IdP claims, the system minimizes the need for multiple passwords and enhances user convenience.

Enhanced Security:
Utilizing hardware-backed methods like Secure Enclave, Platform SSO offers phishing-resistant, passwordless authentication options. This technology ensures that even if network-based attacks occur, the cryptographic keys stored in the Secure Enclave remain secure. Additionally, this integration aligns with macOS security features such as FileVault, ensuring that disk encryption remains robust while supporting SSO functionality.

Flexible Deployment:
Administrators can deploy Platform SSO through Mobile Device Management (MDM) solutions like Microsoft Intune. This central management enables the configuration of detailed policies and payloads—such as AuthenticationMethod, ExtensionIdentifier, and RegistrationToken—to suit various organizational requirements.

Granular Control:
With a comprehensive set of payload keys (as defined in the YAML payload for Extensible SSO), you can fine-tune the SSO experience. These keys cover everything from URL handling and token-to-user mapping to specific behaviors during FileVault unlock, login, and screen unlock scenarios. This granularity ensures that the SSO configuration not only meets security policies but also provides a consistent user experience.

---

How Platform SSO Works

At its core, Platform SSO configures an app extension that acts as an intermediary between the macOS login system and the identity provider. When a user attempts to log in, the system checks if the device is registered for SSO. If it is, the app extension leverages the credentials provided by the IdP to either synchronize with the local account or, in some cases, automatically create a new local account that mirrors the IdP attributes.

This process includes:

• Mapping IdP Claims:
  The system maps claims (such as preferred_username and name) from the identity provider to local account properties using a configuration key known as TokenToUserMapping. This mapping ensures that the local account is consistent with the cloud identity.

• Policy Enforcement:
  Policies such as FileVaultPolicy, LoginPolicy, and UnlockPolicy govern how and when authentication is enforced—whether during boot, at the login window, or when unlocking the screen. These policies include options for offline grace periods and authentication grace periods to prevent lockouts during policy transitions.

• MDM-Driven Configuration:
  Administrators deploy these configurations via MDM solutions like Microsoft Intune, ensuring that devices receive the correct SSO settings automatically and consistently across the organization.

By integrating these features, Platform SSO not only improves security but also significantly enhances the end-user experience by reducing friction during the authentication process.

---

Payload Overview and Structure

The Extensible Single Sign-On payload is defined using a structured YAML format that outlines every aspect of the SSO configuration. This payload acts as a blueprint for how the SSO app extension behaves across various Apple platforms. Below, we break down its key components:

General Payload Attributes

• Title & Description:
  These fields provide a human-readable overview of what the payload does. For instance, the title “Extensible Single Sign-On” and the accompanying description indicate that the payload configures an app extension to handle SSO.
• Payload Type:
  The payloadtype is set to com.apple.extensiblesso, which tells the system that this payload will configure the Extensible SSO functionality.

Supported Operating Systems

The payload defines support for multiple platforms, each with its own set of constraints and features. For example:

• iOS:
  Introduced in iOS 13.0, with settings like multiple installations allowed, supervised mode requirements, and user enrollment specifics.
• macOS:
  Supported from macOS 10.15, it allows both device and user channel configurations, and includes keys that are specific to macOS such as TeamIdentifier (required on macOS) and various SSO policies.
• visionOS and others:
  Additional support is provided for platforms like visionOS, ensuring a unified SSO experience across the Apple ecosystem.

Core Payload Keys

The YAML payload lists several keys—each with specific purposes:

• ExtensionIdentifier & TeamIdentifier:
  • ExtensionIdentifier is a required string that specifies the bundle identifier of the SSO app extension.
  • TeamIdentifier is required on macOS and pairs with the extension identifier to validate the payload.
• Type & Realm:
  • Type (required) specifies the SSO method (e.g., Credential or Redirect), affecting how authentication is processed.
  • Realm is optional and is used for Credential payloads to define the proper realm name.
• ExtensionData:
  This optional dictionary allows arbitrary key-value pairs to be passed through to the extension for custom behaviors.
• URLs & Hosts:
  • URLs (an array) contains URL prefixes for which the extension performs SSO; essential for Redirect payloads.
  • Hosts (an array) is used with Credential payloads to define host or domain names for authentication.
• ScreenLockedBehavior & DeniedBundleIdentifiers:
  These keys determine how SSO requests are handled when the screen is locked and specify any apps that should not use SSO from this extension.
• AuthenticationMethod & RegistrationToken:
  • AuthenticationMethod selects the SSO authentication style (e.g., Password or UserSecureEnclaveKey).
  • RegistrationToken enables silent device registration with the Identity Provider.

PlatformSSO Dictionary

A nested dictionary named PlatformSSO further refines the SSO behavior. It includes:

• AuthenticationMethod (PlatformSSO):
  Allows you to choose between options like Password, UserSecureEnclaveKey, or SmartCard—providing flexibility in how users authenticate.
• UseSharedDeviceKeys:
  A boolean that, when enabled, uses the same signing and encryption keys across all users on the device (only supported on the device channel).
• User Experience Customizations:
  Keys like AccountDisplayName and LoginFrequency help tailor the end-user experience by defining how frequently a full login is required.
• User & Authorization Mappings:
  • TokenToUserMapping defines how attributes from the identity provider (like preferred_username and name) are translated into local account properties.
  • NewUserAuthorizationMode and UserAuthorizationMode set the permission levels (Standard, Admin, or Groups) for new or re-authenticated users.
• Group Definitions:
  Arrays like AdministratorGroups, AdditionalGroups, and the dictionary AuthorizationGroups are used to map IdP group memberships to local authorization rights.
• Policy Arrays (FileVaultPolicy, LoginPolicy, UnlockPolicy):
  These arrays define the behavior during key security operations such as FileVault unlock, login window interactions, and screensaver unlock. They include allowed policy options (e.g., AttemptAuthentication, RequireAuthentication, AllowOfflineGracePeriod, AllowAuthenticationGracePeriod) and related time intervals.
• OfflineGracePeriod & AuthenticationGracePeriod:
  These integer values set the durations (in seconds) for offline access and for the period during which unregistered accounts can continue to operate following a policy update.
• NonPlatformSSOAccounts:
  An array listing local accounts that should not be subject to SSO management, ensuring that legacy or service accounts remain unaffected.

This payload structure gives you a granular control over the SSO configuration, ensuring that each aspect—from URL handling to user account synchronization and policy enforcement—meets both security and usability requirements.

In the next section, we’ll dive deeper into the specific configuration keys and examine how they impact the SSO behavior on macOS devices.

---

Detailed Breakdown of Specific Payload Keys

In this section, we’ll examine each of the key payload fields in detail. Understanding these keys is crucial for tailoring your SSO configuration to match your organization’s security policies and user experience requirements.

General Payload Keys

Extension Identifier:

• Type: String (Required)
• Purpose: Specifies the bundle identifier of the SSO app extension. This value uniquely identifies the extension and must match what is registered in your developer portal.
• Log Example:

[SSO Payload] Using ExtensionIdentifier: com.example.ssoextension

Tip: Ensure the identifier is correct to avoid deployment errors.

Team Identifier:

• Type: String (Optional on iOS/visionOS, Required on macOS)
• Purpose: Associates the payload with your development team. On macOS, this key is essential as it works in conjunction with the ExtensionIdentifier to validate the extension’s authenticity.

Tip: Double-check this value on macOS deployments to ensure compliance with platform requirements.

Type:

• Type: String (Required)
• Allowed Values: Credential, Redirect
• Purpose: Determines the SSO method—whether the extension handles credentials directly (Credential) or works via URL redirection (Redirect).
• Log Example:

[SSO Payload] Authentication type set to Credential.

Realm:

• Type: String (Optional)
• Purpose: For Credential payloads, this key sets the realm name, which should be properly capitalized. It is ignored for Redirect payloads.

Data and URL Handling

Extension Data

• Type: Dictionary (Optional)
• Purpose: Passes custom, arbitrary key-value pairs to the extension.
• Usage Example:

{
  "customKey": "customValue",
  "featureToggle": true
}

Tip: Use this for any extra configuration not covered by standard keys.

URLs

• Type: Array (Optional, required for Redirect payloads)
• Purpose: Lists URL prefixes where the SSO extension applies. Each entry must begin with http:// or https://.
• Subkey:
  • URL (String, Required): A valid URL prefix.
• Log Example:

[SSO Payload] Configured URL: https://login.example.com.

Hosts

• Type: Array (Optional, required for Credential payloads)
• Purpose: Specifies host or domain names that the extension can authenticate. Wildcard entries (e.g., “.example.com”) are supported for matching subdomains.
• Subkey:
  • hostname (String, Required): The actual host or domain name.

Tip: Make sure host entries are unique across all installed payloads.

Security and Behavior Controls

Screen Locked Behavior

• Type: String (Optional)
• Allowed Values: Cancel, DoNotHandle
• Default: Cancel
• Purpose: Determines the system’s response to authentication requests when the screen is locked.
• Log Example:

[SSO Payload] ScreenLockedBehavior set to Cancel.

Tip: Choose ‘DoNotHandle’ if you prefer the system to bypass SSO when the device is locked.

Denied Bundle Identifiers

• Type: Array (Optional)
• Purpose: Lists the bundle identifiers for apps that should not use SSO provided by this extension.
• Subkey:
  • bundleIdentifier (String, Required): The specific app bundle identifier.

Authentication Method

• Type: String (Optional)
• Allowed Values: Password, UserSecureEnclaveKey
• Purpose: Specifies the authentication method for the extension. Note that on macOS, this key is deprecated in macOS 14.0 in favor of the PlatformSSO dictionary’s AuthenticationMethod.
• Log Example:

[SSO Payload] Authentication method set to UserSecureEnclaveKey.

Registration Token

• Type: String (Optional)
• Purpose: Provides a token for silent registration with the Identity Provider. This is required for devices using Platform SSO with a defined AuthenticationMethod and is available on macOS 13 and later.

---

PlatformSSO Dictionary Keys

The PlatformSSO dictionary allows for more granular control over the SSO behavior, particularly on macOS. Key entries include:

Authentication Method (Platform SSO)

• Type: String (Optional)
• Allowed Values: Password, UserSecureEnclaveKey, SmartCard
• Purpose: Selects the specific SSO authentication method to be used in the extension.

Use Shared Device Keys

• Type: Boolean (Optional, defaults to false)
• Purpose: If true, the same signing and encryption keys are used for all users on the device, which is only supported on the device channel.

Account Display Name & Login Frequency

• AccountDisplayName:
  Type: String (Optional)
  Purpose: Sets a custom display name for the account, as shown in notifications and prompts.
• LoginFrequency:
  Type: Integer (Optional)
  Default: 64800 (18 hours)
  Purpose: Determines how frequently the system requires a full login instead of just a credential refresh.

Enable Create User At Login & Enable Authorization

• EnableCreateUserAtLogin:
  Type: Boolean (Optional, default: false)
  Purpose: Enables automatic creation of new local accounts at login using SSO credentials.
• EnableAuthorization:
  Type: Boolean (Optional, default: false)
  Purpose: Allows the use of IdP accounts for local authorization prompts.

Token To User Mapping

• Type: Dictionary (Optional)
• Purpose: Maps IdP token claims to local account properties.
• Subkeys:
  • AccountName: The claim used for the local username (e.g., preferred_username).
  • FullName: The claim used for the user’s full name.
• Log Example:

[TokenToUserMapping] Mapped 'preferred_username' to local account name.

New User Authorization Mode & User Authorization Mode

• Type: String (Optional)
• Allowed Values: Standard, Admin, Groups
• Purpose: Defines the permission level for newly created or re-authenticated accounts.

Group Definitions

• AdministratorGroups & AdditionalGroups:
  Type: Array (Optional)
  Purpose: Lists the groups that confer administrative rights (AdministratorGroups) or other non-administrative privileges (AdditionalGroups) on the device.
• AuthorizationGroups:
  Type: Dictionary (Optional)
  Purpose: Maps specific authorization rights to group names for more granular control.

Policy Arrays: FileVault Policy, Login Policy, Unlock Policy

• Type: Array (Optional)
• Purpose: Define policies that control authentication behavior during critical phases such as:
  • FileVaultPolicy: Applies during FileVault unlock, particularly on Apple Silicon Macs (macOS 15+).
  • LoginPolicy: Governs behavior at the login window.
  • UnlockPolicy: Manages screensaver unlock conditions.
• Subkeys: Each policy array requires a policy key with allowed values such as:
  • AttemptAuthentication
  • RequireAuthentication
  • AllowOfflineGracePeriod
  • AllowAuthenticationGracePeriod
  • (For UnlockPolicy only) AllowTouchIDOrWatchForUnlock
• Log Example:

[FileVaultPolicy] Policy 'AllowAuthenticationGracePeriod' set with a period of 600 seconds.

Offline Grace Period & Authentication Grace Period

• OfflineGracePeriod:
  Type: Integer (Optional)
  Purpose: Sets the time (in seconds) after the last successful SSO login that a local account password can be used offline.
• AuthenticationGracePeriod:
  Type: Integer (Optional)
  Purpose: Determines the duration (in seconds) after a policy update during which unregistered accounts can still log in.

Non Platform SSO Accounts

• Type: Array (Optional)
• Purpose: Lists local account usernames that should not be managed by SSO. This is useful for legacy or service accounts that must remain unaffected by SSO policies.
• Subkey:
  • username (String, Required): The local account name.

By understanding and configuring these keys, you can precisely control the behavior of Platform SSO on your macOS devices. Each key plays a role in ensuring the authentication process is secure, seamless, and aligned with your organizational policies. In the next section, we’ll detail the steps to deploy and manage these settings using Microsoft Intune.

---

Detailed Explanation of Group Keys

IMP: Please note that even if the groups show up on the device as a result of the policy configuration in the MDM profile, Microsoft officially don’t support the feature of configuring Additional, Authorization & Administrator Groups with PSSO and there is no guarantee that these groups will actually facilitate the intended functionality.

Managing user privileges on macOS through Platform SSO is not just about authenticating users—it’s also about ensuring that their local permissions align with the policies defined in your organization. Three key payload parameters play a pivotal role in this mapping:

Additional Groups:

One of the key advantages of Apple’s Platform Single Sign-On (SSO) is its ability to automatically manage local user accounts and group memberships based on an organization’s identity provider (IdP) data.

AdditionalGroups is a critical piece of this puzzle, enabling administrators to create and maintain non-admin local groups on macOS devices without granting full administrative privileges. Here’s everything you need to know.

AdditionalGroups is an array of group names defined in the PlatformSSO payload for macOS. When your device receives this configuration:

1. Ensuring Group Existence:
   The system checks whether each group listed in AdditionalGroups already exists locally. If not, macOS automatically creates it.
2. User Membership Mapping:
   During login, the Platform SSO extension looks at the user’s IdP token. If the user is in a group with a name exactly matching one in AdditionalGroups, macOS adds the user to that local group.

Important:
These groups, by default, do not have administrative privileges. They’re intended for more granular, role-based permissions.

Why Use AdditionalGroups?

• Granular Privilege Control:
  Not all users need the “keys to the kingdom.” With AdditionalGroups, you can assign specialized privileges—like running certain commands with sudo—to a subset of users without granting them full administrator rights.
• Role-Based Access Management:
  Different teams in your organization often have different needs. For instance:
  • Developers might require special tooling or partial sudo privileges.Support Staff might need access to diagnostic commands but not system-wide configuration.
  By defining separate groups (e.g., "com.example.developers", "com.example.support"), you can tailor the exact level of local access each role receives.
• Reduced Security Risk:
  Over-provisioning admin rights increases the attack surface. Restricting privileges to a narrower scope (via AdditionalGroups) helps maintain a robust security posture.
• Automated Consistency:
  Because AdditionalGroups is part of the Platform SSO payload, it ensures that each managed Mac is configured identically. As soon as a user logs in, their local group membership is updated to reflect their IdP memberships—no manual intervention required.

How to Configure AdditionalGroups:

• In your Intune (or MDM) PSSO Profile, provide the list of groups that are created and do not have administrator access.

• Result: macOS creates or confirms the existence of two local groups.

Matching Group Names with Your IdP:

For the user to actually be placed into these local groups, the IdP must claim the same group name. For example, if your IdP (Microsoft Entra) says a user is in the “com.IRL.developers” group, then the Mac sees a match and adds them to the local com.IRL.developers group. If your IdP group name is different (e.g., “DevOps-Scripts”), you must rename or create a matching group name in your IdP, or change the AdditionalGroups entry accordingly.

Example

• IdP Group: com.IRL.developers
• Platform SSO AdditionalGroups: com.IRL.developers
• Outcome: The user is placed in the local com.IRL.developers group at login.

Push a script or configuration profile that creates a file in /private/etc/sudoers.d/.

---

Administrator Groups:

AdministratorGroups is an array of group identifiers (names) defined in your Platform SSO payload that automatically grants local administrator rights to users who are members of those groups in your identity provider (IdP). In practical terms, if a user’s IdP token contains a group name that appears in the AdministratorGroups array, that user’s local macOS account is placed in the admin group. This grants them full administrative privileges on the Mac.

How to Use It:

• Add the Group Name in the PSSO Profile:
  In your Intune configuration, under PlatformSSO → AdministratorGroups, list the group names that correspond to admin-level roles in your organization. For example:

When a user logs in, if their IdP token says they belong to IT-Admins or SecurityOps, the system will add them to the local admin group.

• Exact Name Matching:
  Just like with AdditionalGroups, the local group name must match what the IdP provides. If your IdP group is “IT-Admins” but your configuration says “ITAdmins” (without the hyphen), the user won’t get admin rights.

• Membership Updates:
  If you remove a user from IT-Admins in the IdP, they should lose local admin rights on the next login or re-authentication. Conversely, local changes on the Mac won’t sync back to the IdP.

Why to Use It:

• Centralized Control of Admin Rights:
  By defining who’s in the “admin” group at the IdP level, you avoid manually creating admin accounts on each Mac. Offboarding or changing roles in your IdP automatically updates local privileges.

• Streamlined Onboarding:
  New hires added to IT-Admins or SecurityOps in Entra ID (or another IdP) automatically gain local admin rights on every enrolled Mac, speeding up the provisioning process.

• Audit and Compliance:
  Because admin rights are controlled by the IdP, you can more easily track who has administrative privileges across the organization, satisfying compliance or audit requirements.

Impact:

• Full Local Admin Privileges:
  A user placed in admin can perform any system-wide changes, install software, modify system settings, and more. This is powerful but also increases the security risk if misused or compromised.
• One-Way Mapping:
  As with other group mappings, the user’s membership is evaluated at login time. Removing a user from the IdP group is the recommended way to revoke admin privileges—no need to log into each Mac to do so manually.
• Potential Security Trade-Offs:
  Because this key grants full local admin access, it’s essential to use it sparingly and only for users who genuinely need broad privileges.

Practical Example:

Scenario: IT Support Team with Admin Rights

1. Entra ID Group: “IT-Admins”
   • Members: Tier 2 or Tier 3 support engineers who need to install apps, troubleshoot network settings, etc.
2. Platform SSO Payload Snippet:

3. Result:
   • Users can install software, change system preferences, and run admin-level commands without additional configuration.
   • Removing a user from “IT-Admins” in Entra ID revokes their local admin rights at next sign-in.

---

Authorization Groups:

AuthorizationGroups is a dictionary in the Platform SSO payload that allows you to map specific macOS authorization rights (for example, changing network settings or printer configurations) to a local group. If a user is in that local group, they’re granted the corresponding authorization right without needing full administrator privileges. This differs from:

• AdditionalGroups: Creates or ensures local groups exist, but does not inherently link them to specific system privileges or rights.
• AdministratorGroups: Grants full admin rights by placing users in the local admin group.

How to Use It:

• Define the Authorization Right → Group Mapping
  In your PSSO profile, you specify a dictionary where each key is a macOS authorization right, and the value is the group name you want to associate with that right. For example:

• Key (e.g., system.preferences.network): A macOS authorization right.
• Value (e.g., com.example.networkAdmins): A local group that must match the IdP group name for membership.

• Ensure the Group Exists
  • To guarantee the local group is created, you can also add it under AdditionalGroups.
  • This way, macOS automatically creates the groups "com.example.networkAdmins" and "com.example.printingAdmins" if they don’t exist.
  • If the user’s IdP token indicates they’re in com.example.networkAdmins, they’re granted rights to modify network settings without being full admins.
  • For example:

PlatformSSO:
  AdditionalGroups:
    - Group: "com.example.networkAdmins"
    - Group: "com.example.printingAdmins"
  AuthorizationGroups:
    system.preferences.network: "com.example.networkAdmins"
    system.preferences.printing: "com.example.printingAdmins"

• Exact Name Matching
  As with other group-based mappings in Platform SSO, the IdP group name must match exactly what you specify in AuthorizationGroups. If your IdP says “NetworkAdmins” but your payload says “com.example.networkAdmins,” there’s no match, and the user won’t receive that right.

Why to Use It:

• Granular System Preferences Control
  Instead of making someone a full admin (via AdministratorGroups) or messing with partial sudo for arbitrary commands, AuthorizationGroups lets you selectively grant rights to system preferences or other macOS-defined authorization checks (e.g., system.preferences.network, system.preferences.printing, etc.).

• Reduced Security Risk
  Giving users the ability to change network or printing settings might be necessary for their role, but you don’t want them installing software or modifying core system files. AuthorizationGroups provides that middle ground—fine-tuned access to a subset of system preferences.

• Centralized Role Management
  By controlling group membership in your IdP (e.g., Microsoft Entra ID), you can dynamically grant or revoke these rights across all managed Macs. Removing a user from com.example.networkAdmins in the IdP removes their local ability to change network settings at the next login.

Practical Example:

Scenario: Network and Printer Rights

1. IdP Groups:
   • com.example.networkAdmins (for network configuration)
   • com.example.printingAdmins (for printer setup)
2. PSSO Payload Snippet:

PlatformSSO:
  AdditionalGroups:
    - Group: "com.example.networkAdmins"
    - Group: "com.example.printingAdmins"
  AuthorizationGroups:
    system.preferences.network: "com.example.networkAdmins"
    system.preferences.printing: "com.example.printingAdmins"

3. Result:
   • Any user whose IdP token shows they’re in com.example.networkAdmins can change network settings in System Settings without being a full admin.Anyone in com.example.printingAdmins can add or remove printers.If a user is removed from these groups in the IdP, they lose those rights upon their next authentication.

---

Next Steps: LoginPolicy, OfflineGracePeriod, and FileVaultPolicy

Having covered various group-based configurations (e.g., AdditionalGroups, AdministratorGroups, and AuthorizationGroups), we now turn to three key policies that govern how password-based Platform SSO operates under different conditions. Specifically:

• LoginPolicy defines how the system enforces single sign-on at the macOS login window.
• OfflineGracePeriod determines how long a user’s local password remains valid if the device is offline after a successful SSO login.
• FileVaultPolicy extends SSO behavior to FileVault unlock scenarios on Apple Silicon Macs.

These policies collectively ensure a balanced approach to security and usability—preventing unauthorized access while avoiding lockouts in legitimate offline or FileVault contexts. In the following sections, we’ll explore each key’s purpose, configuration, and practical examples to help you fine-tune your organization’s macOS Platform SSO deployment.

Login Policy:

LoginPolicy is an array of policy items that define how Platform SSO behaves at the macOS login window when AuthenticationMethod is set to Password. Each policy item has a policy key whose value can be one of the following:

• AttemptAuthentication
• RequireAuthentication
• AllowOfflineGracePeriod
• AllowAuthenticationGracePeriod

How to Use It:

• Configuration in the PSSO Payload:

• Possible Policy Values:
  • AttemptAuthentication
    • The system tries to authenticate with Platform SSO before letting the user log in.
    • If the device is offline, or if SSO fails, the user can still log in with their cached local password (assuming it matches).
  • RequireAuthentication
    • A successful Platform SSO authentication is mandatory at login.
    • If the device is offline and AllowOfflineGracePeriod is also set, the user may still log in within that offline grace window.
    • If the device is online and credentials are wrong, the user must re-authenticate with the IdP.
  • AllowOfflineGracePeriod
    • Permits using the OfflineGracePeriod key if the device is offline.
    • If not set, offline access is denied when RequireAuthentication is active.
  • AllowAuthenticationGracePeriod
    • Permits unregistered local accounts to log in within the AuthenticationGracePeriod after a policy update.
    • If not set, and the user isn’t registered for Platform SSO, they’re locked out.

Why to Use It:

• Stricter Security at Login:
  RequireAuthentication ensures that users must be verified by the IdP at login, minimizing the risk of using stale or compromised local credentials.
• Fallback for Offline or Transitional Scenarios:
  AllowOfflineGracePeriod and AllowAuthenticationGracePeriod prevent lockouts when users are offline or if the policy has just changed. This balance helps maintain usability while enforcing strong authentication.

Impact:

• Online vs. Offline Behavior:
  • If RequireAuthentication is set without AllowOfflineGracePeriod, users cannot log in offline unless their local password still works within the last successful SSO session.
  • If you set AllowAuthenticationGracePeriod but not RequireAuthentication, users might bypass immediate SSO registration for a limited time after a policy update.
• Grace Period Dependencies:
  • If you include AllowOfflineGracePeriod, you must specify an OfflineGracePeriod value.
  • If you include AllowAuthenticationGracePeriod, you must specify an AuthenticationGracePeriod value.

Practical Example:

Scenario: Strict Login with Offline Flexibility

• Explanation:
  • RequireAuthentication means the Mac must authenticate with the IdP at the login window if online.
  • AllowOfflineGracePeriod plus OfflineGracePeriod: 3600 (1 hour) means if the user is offline, they can still log in with their cached local password within one hour of their last successful SSO login.

Result:

If the Mac is offline, they have a 1-hour grace window to use their local password before requiring an online SSO check again. Users can’t bypass SSO if the Mac is online.

---

Offline Grace Period:

When you enable RequireAuthentication in Platform SSO (particularly at the login window or FileVault unlock), you may also want to allow users to access their device when it’s offline—up to a certain limit. That’s where OfflineGracePeriod comes in. It specifies how long a user can continue to use their cached local password offline after their most recent successful SSO authentication.

What It Is:

OfflineGracePeriod is an integer (in seconds) that defines the duration after the last successful Platform SSO login during which a user can log in with their local password, even if the Mac is offline. This key becomes essential when you include a policy item like AllowOfflineGracePeriod in LoginPolicy or FileVaultPolicy.

How to Use It:

• Add to Your PSSO Payload:
  • In this example, OfflineGracePeriod is set to 3600 seconds (1 hour).
  • The presence of AllowOfflineGracePeriod within the LoginPolicy array tells macOS to respect this offline window.

Applies to:

• LoginPolicy at the macOS login window.
• FileVaultPolicy when unlocking a FileVault-encrypted volume (particularly on Apple Silicon Macs), if AllowOfflineGracePeriod is set there as well.

Why to Use It:

• Prevent Lockouts Offline:
  If the user is on a flight, in a remote location, or otherwise without internet access, OfflineGracePeriod allows them to continue using their local password for a limited time, rather than being forced to reauthenticate with the IdP.
• Balance Security and Usability:
  By choosing an appropriate offline window (e.g., 30 minutes, 1 hour, or 8 hours), you reduce the risk of credential misuse while still supporting legitimate offline scenarios.

Impact:

1. Enforced Time Window:
   Once the OfflineGracePeriod expires, the user must connect to the internet and reauthenticate via the IdP to continue using their account.
2. Synchronization with Policy Updates:
   If you change OfflineGracePeriod or remove AllowOfflineGracePeriod, it can impact users who rely on offline logins. Plan updates accordingly.
3. User Experience:
   The system doesn’t necessarily notify users that their offline grace period has started or will expire—so clear communication (e.g., in user training or documentation) can help.

Example Scenario:

Scenario: 8-Hour Offline Window

PlatformSSO:
  AuthenticationMethod: Password
  LoginPolicy:
    - policy: RequireAuthentication
    - policy: AllowOfflineGracePeriod
  OfflineGracePeriod: 28800  # 8 hours

The user must authenticate with the IdP at least once while online. After that, if the device goes offline, they have up to 8 hours to use their local password before needing to reconnect.

---

FileVault Policy:

When you enable Password-based Platform SSO on Apple Silicon Macs running macOS 15 or later, FileVaultPolicy governs how SSO authentication is handled at FileVault unlock. By configuring various policy items—like RequireAuthentication or AllowOfflineGracePeriod—you can balance strict security with practical offline access, ensuring that users can still unlock their devices under certain conditions without bypassing SSO entirely.

What It Is:

FileVaultPolicy is an array of policy items—each containing a policy key—that define how Platform SSO interacts with FileVault on Apple Silicon Macs. Possible values for policy include:

• AttemptAuthentication
• RequireAuthentication
• AllowOfflineGracePeriod
• AllowAuthenticationGracePeriod

How to Use It:

• Configure your PSSO Payload:
  • This example enforces SSO at FileVault unlock (RequireAuthentication), but also allows offline access for up to 1 hour (OfflineGracePeriod: 3600) and a grace period for unregistered accounts (AllowAuthenticationGracePeriod) with AuthenticationGracePeriod: 600 seconds (10 minutes).

• Applies Only to Apple Silicon Macs (macOS 15+)
  • On Intel Macs or earlier OS versions, FileVaultPolicy is ignored.
  • If you’re managing a mixed environment, consider separate policies or fallback configurations for older hardware.

Policy Items Overview:

• AttemptAuthentication: The system tries to authenticate with Platform SSO first. If offline or incorrect, the local password may suffice.
• RequireAuthentication: Forces a valid SSO login if the device is online; if offline, AllowOfflineGracePeriodmust be set or the user is locked out.
• AllowOfflineGracePeriod: Permits using the OfflineGracePeriod for local unlock when offline.
• AllowAuthenticationGracePeriod: Allows unregistered local accounts to unlock within the AuthenticationGracePeriod after a policy update

Why to Use It:

• Enhanced Security at Disk Unlock
  With FileVault encryption, the user must unlock the disk before macOS loads. Requiring SSO ensures that the user is genuinely authenticated against your IdP, minimizing risks associated with stolen or compromised devices.
• Offline Flexibility
  Some users need to unlock their device while traveling or in areas without internet access. Allowing an offline grace period prevents total lockouts when connectivity is unavailable.

Impact:

1. Stricter Disk-Level Authentication
   • If RequireAuthentication is active and the Mac is online, the user must pass SSO. A wrong password or unsuccessful IdP login will block disk unlock.
2. Time-Based Exceptions
   • OfflineGracePeriod: Grants a limited window for using local credentials offline.
   • AuthenticationGracePeriod: Lets unregistered local accounts unlock for a short time post-policy update.
3. Hardware-Specific
   • Only Apple Silicon devices running macOS 15+ respect FileVaultPolicy. Intel Macs rely on local passwords for FileVault unlock, independent of SSO.

Example Scenario:

PlatformSSO:
  AuthenticationMethod: Password
  FileVaultPolicy:
    - policy: RequireAuthentication
    - policy: AllowOfflineGracePeriod
  OfflineGracePeriod: 7200

Result:

• RequireAuthentication ensures that if the Mac is online, the user must pass SSO to unlock FileVault.
• AllowOfflineGracePeriod plus OfflineGracePeriod: 7200 (2 hours) allows a short offline window for using the local password if no network is available.
• Users can’t bypass SSO when online, ensuring strong authentication.
• Offline convenience is maintained for up to 2 hours after their last successful SSO login, reducing friction for legitimate users who may not have internet access at boot.

---

Conclusion

Implementing Platform Single Sign-On (SSO) on macOS offers a unified, secure, and user-friendly authentication experience. From mapping specific permissions with AuthorizationGroups, to fine-tuning the login window using LoginPolicy, and safeguarding FileVault unlock scenarios with FileVaultPolicy, each configuration key provides a building block toward a robust, role-based security model. Meanwhile, OfflineGracePeriod ensures that users aren’t locked out when legitimate offline access is needed.

Key Takeaways

1. Granular Control:
   • AdditionalGroups helps create non-admin local groups for partial privileges (e.g., limited sudo access).
   • AdministratorGroups grants full local admin rights based on IdP membership.
   • AuthorizationGroups ties specific macOS authorization rights (like system.preferences.network) to a local group, avoiding full admin elevation.
2. Balanced Security:
   • LoginPolicy and FileVaultPolicy govern how strictly SSO is enforced at login or disk unlock, with options like RequireAuthentication for maximum security or AttemptAuthentication for a more flexible approach.
   • OfflineGracePeriod and AuthenticationGracePeriod offer controlled leeway, reducing lockouts in legitimate offline scenarios.
3. MDM Integration:
   • Deploying these settings through Microsoft Intune automates policy enforcement and ensures consistent, organization-wide security posture.
   • Fine-tuning keys in the Settings Catalog—like the Extensible SSO payload—lets you manage everything from user groups to login grace periods, all from a central console.
4. One-Way Mapping:
   • Local macOS group membership follows your IdP group names exactly, so maintain consistent naming in your identity provider and your Intune profile.
   • Removing a user from an IdP group revokes their local privileges at the next login, simplifying offboarding and compliance.

By carefully selecting and combining these payload keys, you can create a macOS SSO environment that is both secure and practical. Users enjoy a frictionless login experience that syncs with their cloud credentials, while IT retains centralized control over who can do what—and when—on each device. Whether you’re rolling out single sign-on for the first time or refining an existing deployment, the flexibility of Platform SSO on macOS ensures you can meet your organization’s evolving security and productivity needs.