# Configure settings for Extensible Single Sign-on 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](https://www.hexnode.com/mobile-device-management/help/platform-sso-macos-hexnode-uem/) (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 --------------------------------- Note:Extensible SSO is supported on devices running macOS 10.15 and later. 1. Log in to your Hexnode portal. 2. Navigate to **Policies**. 3. Select an existing policy or create a new one by clicking on **New Policy**. 4. Go to **macOS > Security > Extensible SSO** and click on **Configure.** 5. 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 SettingsDescriptionExtension identifierProvide 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 identifierProvide the team identifier for the app extension. The team identifier is a unique alphanumeric string used to identify the app extension.SSO blocklistEnter 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 behaviorLock screen behavior consists of two options: - **Cancel authentication requests** – This cancels authentication requests when the device is locked. - **Do not handle authentication requests** – This allows authentication requests to proceed without SSO when the device is locked. Select one from the dropdown menu. ### Credential settings SettingsDescriptionRealmProvide 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.HostsProvide 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.URLSpecify 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: SettingsDescriptionAllow saving password in Keychain AccessWhen enabled, the user’s password will be saved in the Keychain app. Disabled by default.Require complex password valueWhen enabled, the system requires a complex password as suggested by Active Directory. Disabled by default.Allow password changeWhen enabled, the user can change the password. Disabled by default.Minimum password lengthAdmins can set the minimum password length. The default value is 8.Minimum password ageAdmins can set the minimum age for passwords. The default value is 42 days.Password expiry alertAdmins 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 historyAdmins 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. Note: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. SettingsDescriptionRegistration tokenEnter 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 NameSpecifies 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 keysEnables 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 MacRegister during Setup AssistantEnables 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. SettingsDescriptionMap token to local userExtracts 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: 1. Standard: Creates a standard user account. 2. Admin: Creates a user account with admin privileges. 3. Groups: Adds the user to the specified local macOS groups. 4. Temporary: Creates a temporary user account for short-term access. 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: - Password - Smart Card - Access Key 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: - PKCS12 - SCEP - ACME Enable authorizationEnable this option to allow users to use cloud IdP credentials for actions that require an authorization prompt, such as administrator approval actions.User authorization typeSelect 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. Note:- 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. SettingsDescriptionLogin frequencyAdmin 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 PolicyDefines how Platform SSO authentication is applied at the FileVault unlock screen on Apple silicon Macs. Administrators can select one of the following options: - **None**: Uses the default FileVault authentication behavior. - **Attempt Authentication**: Attempts Platform SSO authentication during FileVault unlock and falls back to local credentials if the identity provider is unavailable. - **Require Authentication**: Requires successful authentication from the identity provider to unlock FileVault. Login Window PolicyDefines how Platform SSO authentication is applied at the macOS Login Window. Administrators can select one of the following options: - None - Attempt Authentication - Require Authentication Screensaver Unlock PolicyDefines how Platform SSO authentication is applied when users unlock a session after the screensaver is activated. Administrators can select one of the following options: - None - Attempt Authentication - Require Authentication Exclusion listAdmin 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 periodAdmin 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 periodAdmin 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. Note: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 1. Navigate to **Policy Targets**. 2. Click on **+Add Devices**. 3. Select the devices and click **OK**. 4. 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 1. From ‘Policies’, check the policies to be associated. 2. Click on **Manage → Associate Targets** and select the device. 3. 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. Note: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. ### 2. SSO Extension application unavailable during Setup Assistant **Symptom**: Platform SSO registration fails during Setup Assistant with an error indicating that sign-in cannot be completed because the SSO extension is unavailable. **Cause**: When **Register during Setup Assistant** is enabled, macOS attempts to complete Platform SSO registration during the initial setup flow. If the IdP application containing the required SSO extension (such as Microsoft Company Portal) is not yet installed on the device, authentication cannot proceed. **Solution**: Allow the IdP application and SSO extension installation to complete. Then select Try Again in Setup Assistant to continue Platform SSO registration. Related Documentation --------------------- - [Configure Associated Domains on macOS devices](https://www.hexnode.com/mobile-device-management/help/configure-associated-domains-on-macos-devices/)