Category filter
Configure settings for Extensible Single Sign-on for macOS devices
TL;DR
Hexnode UEM extends the macOS Extensible SSO policy to support Platform SSO configurations, enabling administrators to configure SSO extension settings, authentication methods, user mapping, account creation, authorization, and security policies for macOS devices.
Executive Summary
Extensible Single Sign-On (SSO) is a feature introduced by Apple to enhance the login experience for users accessing enterprise apps or websites. It allows users to access supported resources without repeatedly entering their credentials. Platform Single Sign-On (Platform SSO) extends this framework by integrating the identity provider with supported macOS authentication workflows. It allows users to use their organizational identity for Mac sign-in and application access. This guide covers the configuration workflow for Extensible SSO and Platform SSO settings in Hexnode UEM, from identity provider selection to policy association with devices or groups.
Configure Extensible SSO settings
Extensible SSO is supported on devices running macOS 10.15 and later.
- Log in to your Hexnode portal.
- Navigate to Policies.
- Select an existing policy or create a new one by clicking on New Policy.
- Go to macOS > Security > Extensible SSO and click on Configure.
- Select the identity provider for the Extensible SSO configuration. The available options are Custom, Microsoft Entra ID, Okta and Google Workspace.
The selected identity provider determines how the SSO extension details are configured. The Extension Identifier and Team Identifier are required to identify the SSO extension that handles authentication requests on the Mac.
- Microsoft Entra ID, Okta, and Google Workspace: The required Extension Identifier and Team Identifier values are automatically populated based on the selected identity provider.
- Okta: Enter the Okta Org Domain associated with your organization’s Okta tenant when prompted. This domain identifies the Okta tenant used for authentication and can be obtained from the organization’s Okta administration console.
- Custom: Use this option for identity providers other than the above-mentioned ones. Administrators must manually enter the Extension Identifier and Team Identifier of the IdP’s SSO extension, which can be obtained from the SSO extension configuration provided by the identity provider.
Extensible SSO supports three SSO extension types:
- Credential: Uses stored credentials to authenticate users without requiring them to re-enter their login details. This is mainly used for challenge-response authentication, where a request is sent from the application to the authentication server.
- Redirect: Facilitates authentication via modern protocols like OAuth, SAML 2.0, or OpenID Connect by redirecting users to an external identity provider (IdP) like Microsoft Active Directory, for authentication, and then redirects back to the application after successful authentication. Upon successful login, the session token is stored and used for future authentication.
- Kerberos: The Kerberos extension on Apple devices enables secure authentication by using encrypted tickets from a central server (Key Distribution Center). This enables the device users to effortlessly authenticate resources such as websites and applications.
Redirect settings
| Settings | Description |
|---|---|
| Extension identifier | Provide the unique bundle identifier of the app extension that performs Single Sign On. The extension identifier links a specific SSO extension to the corresponding application, ensuring the authentication requests are routed correctly. For instance, the extension identifier could be com.example.app.ssoextension. |
| Team identifier | Provide the team identifier for the app extension. The team identifier is a unique alphanumeric string used to identify the app extension. |
| SSO blocklist |
Enter the bundle identifier for apps that don’t use SSO provided by the extension. Multiple values can be added to this field.
Note:
SSO blocklist is supported on devices running macOS 12 and later.
|
| Lock screen behavior |
Lock screen behavior consists of two options:
Select one from the dropdown menu. |
Credential settings
| Settings | Description |
|---|---|
| Realm | Provide the DNS domain name. It should be capitalized. For instance, if your domain name is example.com, then the realm name would be EXAMPLE.COM. |
| Hosts | Provide the domain name that can be authenticated via the app extension. Multiple values can be added to this field. Host or domain names are matched regardless of letter case. For instance, example.com and EXAMPLE.COM are considered the same. |
| URL | Specify the identity provider URLs where the app extension performs SSO. The URLs must begin with http:// or https:// and must be unique across all policies. |
Kerberos settings
When setting up the policy for Kerberos, the extension identifier and team identifier are auto populated as com.apple.AppSSOKerberos.KerberosExtension, and apple respectively. The password settings for the apps and websites that perform SSO can be configured with the following options:
| Settings | Description |
|---|---|
| Allow saving password in Keychain Access | When enabled, the user’s password will be saved in the Keychain app. Disabled by default. |
| Require complex password value | When enabled, the system requires a complex password as suggested by Active Directory. Disabled by default. |
| Allow password change | When enabled, the user can change the password. Disabled by default. |
| Minimum password length | Admins can set the minimum password length. The default value is 8. |
| Minimum password age | Admins can set the minimum age for passwords. The default value is 42 days. |
| Password expiry alert | Admins can specify the number of days before password expiration when the system sends a notification to the user. The default value is 14 days. |
| Password history | Admins can set the number of past passwords that cannot be reused on the domain. The default value is 10. |
Configure Platform SSO
Platform SSO configuration allows administrators to extend Extensible SSO settings to macOS authentication workflows by enabling identity provider authentication for Mac sign-in and supported applications and websites.
Before configuring Platform SSO, ensure that
- The Mac is running macOS 14 or later for Platform SSO configuration through Hexnode UEM.
- A Platform SSO-compatible app containing an SSO extension that supports the selected IdP is installed
- The SSO Extension Type is set to Redirect.
Platform SSO settings
Select the Enable Platform SSO checkbox to enable Platform SSO settings in the Extensible SSO policy.
Platform SSO supports the following Authentication Methods:
- Password: Allows users to sign in to the Mac using their IdP credentials instead of their local account password and provides users SSO access to supported applications and websites. The IdP password is synchronized with the local account password.
- User Secure Enclave Key: Allows users to authenticate with the IdP using a hardware-bound cryptographic key generated and protected by the Mac’s Secure Enclave. During user registration, the Secure Enclave-backed key is associated with the user’s IdP identity. During authentication, the SSO extension uses the key to verify the user’s identity with the IdP without requiring an IdP password.
- Smart Card: Allows the user to authenticate with the IdP using a smart card certificate stored on a PIV-compatible smart card or hardware token, such as a YubiKey with PIV support. The user enters the associated PIN to authorize certificate usage, enabling certificate-based authentication to macOS, supported applications, and websites.
- Access Key: Allows users to authenticate with the IdP using pass stored in Apple Wallet. During sign-in, the user presents the access key from Apple Wallet to the Mac through a supported NFC reader. Platform SSO uses the access key to authenticate the user with the IdP. Once verified, the user is authenticated without entering a password. This option is available only for the New user authentication method option described below.
| Settings | Description |
|---|---|
| Registration token | Enter the registration token generated by the IdP to allow the Mac to register with the identity provider automatically during Platform SSO. For example, a Microsoft Entra registration token can be specified as {{DEVICEREGISTRATION}} |
| Account Name | Specifies the display name for the Platform SSO account. This name appears in system notifications during Platform SSO registration, and authentication prompts when signing in, helping users identify the account they need to use. |
| Use shared device keys | Enables the Mac to use shared cryptographic signing and encryption keys for users authenticating through Platform SSO on the same device. Administrators can enable this option for shared Mac deployments where multiple users need to sign in to a single Mac |
| Register during Setup Assistant | Enables the Mac to require IdP authentication during the initial Setup Assistant process for devices enrolled through Automated Device Enrollment (ADE). The user must complete authentication before they can access macOS. |
User Mapping & Creation settings
These settings control how IdP user information is mapped to local macOS accounts, how new local accounts are created during Platform SSO authentication, and how user privileges are assigned.
| Settings | Description |
|---|---|
| Map token to local user | Extracts user claims from the IdP authentication token and maps them to the corresponding attributes of the local macOS account. |
| Server Account Name (Available when Map token to local user is enabled) |
Specifies the IdP token claim used as the local macOS account name. Admin configures the claim that contains the user’s account identifier. For Microsoft Entra ID, this can use claims such as com.apple.PlatformSSO.AccountShortName or preferred_username. |
| Server Full Name (Available when Map token to local user is enabled) |
Specifies the IdP token claim used to set the display name of the local macOS user. Admin configures the token claim that contains the user’s display name. For Microsoft Entra ID, this is typically configured using the name claim. |
| Create New User at Login (Available when Use Shared Device Key is enabled) |
When enabled, this option automatically creates a local macOS user account when a user authenticates their IdP account for the first time. This allows users to sign in without requiring a pre-created local account. |
| New user authorization type (Available when Create New User at Login is enabled) |
Select the authorization type assigned to newly created user accounts based on the required user privileges. Available options are:
|
| New user authentication method (Available when Create New User at Login is enabled) |
Select the authentication method to be used when the new user signs in for the first time. Available options are:
|
| Group ID (Available when New User authentication method is set to Access Key) |
Specifies the reader group identifier associated with the Access Key. Admin can obtain this value from the organization’s access control system provider. |
| Issuer Certificate (Available when New User authentication method is set to Access Key) |
Upload the certificate used to verify the issuer of the Access Key’s Terminal Identity. Admin can obtain this certificate from the organization’s access control system provider. |
| Select identity source (Available when New User authentication method is set to Access Key) |
Select the source used to provision the Terminal Identity on the device. Available options are:
|
| Enable authorization | Enable this option to allow users to use cloud IdP credentials for actions that require an authorization prompt, such as administrator approval actions. |
| User authorization type | Select the authorization level applied to a user account each time the user authenticates through Platform SSO. Available options are Standard, Admin, and Groups. |
| Admin groups (Available when Authorization is selected as Groups) |
Admin can specify the IdP groups whose members should receive administrator privileges. |
| Additional groups (Available when Authorization is selected as Groups) |
Admin can specify additional local macOS groups to which authenticated users are added. If the specified groups do not already exist, macOS creates them automatically. |
Security Policy settings
Security Policy settings control how Platform SSO authentication is applied during login, FileVault unlock, and screensaver unlock. They also define authentication behavior during offline access through grace period settings.
- For compatibility with FileVault Policy, Login Window Policy, Screensaver Unlock Policy, Exclusion List, Offline Grace Period, and Authentication Grace Period, use macOS 15 or later.
- FileVault Policy, Login Window Policy, and Screensaver Unlock Policy only apply when Password is selected as the Platform SSO authentication method.
| Settings | Description |
|---|---|
| Login frequency | Admin can specify the maximum duration of a Platform SSO authentication session before requiring full authentication instead of session refresh. If not configured, the default value is 18 hours. |
| FileVault Policy |
Defines how Platform SSO authentication is applied at the FileVault unlock screen on Apple silicon Macs. Administrators can select one of the following options:
|
| Login Window Policy |
Defines how Platform SSO authentication is applied at the macOS Login Window. Administrators can select one of the following options:
|
| Screensaver Unlock Policy |
Defines how Platform SSO authentication is applied when users unlock a session after the screensaver is activated. Administrators can select one of the following options:
|
| Exclusion list | Admin can specify the local macOS accounts that are excluded from Platform SSO policies like FileVault Policy, Login Window Policy, or Screensaver Unlock Policy. |
| Offline grace period | Admin can specify the number of days users can sign in with the local account password while the Mac is offline after successfully authenticating through Platform SSO. A value of 0 disables the Offline Grace Period. |
| Authentication grace period | Admin can specify the number of days unregistered local accounts can be used after a Platform SSO policy is applied. A value of 0 disables the Authentication Grace Period. |
When Require Authentication is selected for Login Window, FileVault, or Screensaver Unlock policies, configure an appropriate Offline Grace Period to provide a fallback authentication period when the Mac cannot communicate with the identity provider. This helps prevent users from being locked out due to temporary network or IdP availability issues.
Custom Configuration
Admins can upload a .plist file containing key-value pairs for custom configuration of the SSO extension.
Associate Policies with Devices / Groups
If the policy has not yet been saved
- Navigate to Policy Targets.
- Click on +Add Devices.
- Select the devices and click OK.
- Click on Save to apply the policies to devices.
Apart from devices, you can also associate the policies with device groups, user and user groups from ‘Policy Targets’.
If the policy has been saved, you can associate it by another method
- From ‘Policies’, check the policies to be associated.
- Click on Manage → Associate Targets and select the device.
- Click on Associate to apply policy to the devices.
What happens on the device?
Extensible SSO
After the Extensible SSO configuration is applied, users can access configured applications without being prompted to enter their credentials again after completing the initial authentication. For example, when Microsoft Teams is configured to use Extensible SSO, the user can authenticate once and continue accessing the application without additional credential prompt.
Platform SSO
After the Platform SSO configuration is successfully deployed, the user must complete the Platform SSO registration on the device. A registration prompt appears on the device to guide the user through the registration process.
Users can also manually initiate registration from
System Settings > Users & Groups > Edit next to Network Account Server > Register next to Mac SSO Extension under Platform Single Sign-on.
When the registration window appears, select Continue, provide the local macOS account credentials, and then authenticate using the credentials for the configured identity provider (IdP).
After successful registration, when Password is selected as the authentication method, the IdP password is synchronized with the registered local macOS account. At the macOS Login Window, users can sign in using the synchronized password for the existing local account. Alternatively, users can select Other and sign in using their IdP credentials to access the same account.
Troubleshooting Guides
1. Platform SSO Registration Issues
Symptom: Platform SSO authentication or password synchronization does not work correctly after the device has been registered.
Cause: The Platform SSO registration state between the Mac device, local user account, and identity provider may become invalid or out of sync.
Solution:
Users can repair the existing Platform SSO registration by navigating to:
System Settings > Users & Groups > Network Account Server > Edit > Repair
The Repair option initiates the Platform SSO registration process again and allows the device to establish the required association with the identity provider.
Frequently Asked Questions
1. Is user interaction required after deploying Platform SSO?
Yes. Deploying the Platform SSO configuration enables the workflow on the Mac, but users must complete the Platform SSO registration process with the configured identity provider. During registration, the user authenticates with the IdP to associate the IdP account with the local macOS account.
3. What happens if the user dismisses the Platform SSO registration prompt?
If the user closes or dismisses the Platform SSO registration prompt, the registration process is not completed. The registration notification appears again when the user signs back in to the Mac after signing out.
3. What happens if the required IdP application for Platform SSO is not installed on the Mac?
Platform SSO requires a compatible IdP application containing the SSO extension to be installed on the device. If the required application is missing, the SSO extension cannot handle Platform SSO authentication requests. Administrators can deploy the required IdP application through Hexnode UEM before configuring Platform SSO.
4. Why does a newly created Platform SSO user receive different privileges after signing in again?
When a user account is first created through Platform SSO, macOS applies the New user authorization type setting. After the account exists, the User authorization type setting is applied during subsequent logins. For example, if New user authorization type is set to Admin and User authorization type is set to Standard, the newly created account receives administrator privileges during creation. During the next login, the account privileges are updated according to the User authorization type setting.
