Skip to main content

Apple Platform SSO Policy

Updated over a week ago

The Apple Platform SSO Policy allows organizations to integrate macOS login with their identity provider (IdP) using Apple’s Platform Single Sign-On (SSO) framework.
This policy enables users to sign into their macOS devices using their Google, Microsoft Entra ID (Azure AD), or Okta credentials—improving security, reducing password fatigue, and centralizing authentication across the enterprise.

Swif.ai provides full support for Apple Platform SSO, allowing IT teams to deploy SSO at macOS login using standard OIDC configuration parameters.

If FileVault is Enabled ⚠️

Before configuring or deploying the Apple Platform SSO Policy, Platform SSO depends on macOS Secure Token and FileVault integration. If FileVault is enabled:

  • Platform SSO will not function correctly

  • Platform SSO will not appear automatically at the login window

  • Authentication flows may fail or appear misconfigured

Required Setup If FileVault is Enabled

When assigning the Apple Platform SSO Policy:

  • Set Apple Login Window Policy -> “Disable automatic login if FileVault is enabled = true” and assign to the same group of devices,

    • If FileVault is enabled and this value is not true, the device can auto-login after FileVault unlock, and the SSO app/login flow will not appear after FileVault login.

  • Since March 2026, when you create an Apple Platform SSO Policy, we automatically add “Disable automatic login if FileVault is enabled = TRUE” to the Apple Platform SSO Policy. But if you still have Apple Login Window Policy on the same device, remember to set “Disable automatic login if FileVault is enabled” to TRUE. We recommend you use the field from Apple Platform SSO Policy to avoid confusion.

  • The user first sees the username/password screen after rebooting to unlock FileVault. After FileVault is unlocked, the system still requires a separate user login. Then, upon computer restart, they will be able to view the Platform SSO login screen directly.

Failing to enable “Disable automatic login if FileVault is enabled” may result in Platform SSO not appearing or functioning properly at the login window.

Overview

With Apple Platform SSO, organizations can:

  • Enforce corporate identity login at macOS startup

  • Sync local macOS user accounts with IdP user attributes

  • Automatically create and manage local users

  • Enable password synchronization, token-based login, and SSO across apps

  • Improve compliance by removing local password handling

Swif.ai’s Platform SSO integration works with:

  • Google Workspace

  • Microsoft Entra ID (Azure AD)

  • Okta Workforce Identity Cloud

Full implementation guides are available here:

Requirements

  • macOS 12.0+

  • Device must be enrolled through Swif.ai MDM

  • Identity provider must support OIDC (OpenID Connect)

  • Configuration requires admin permissions in Swif.ai and your IdP

Configurable Settings

The policy allows administrators to map essential OIDC values that macOS requires to establish Platform SSO.
Below are all available configuration options.

Create Admin User

Determines whether the account created during Platform SSO onboarding is a local admin.

Setting

Description

True

New users created via SSO are local admins

False

New users are standard local users

Minimum macOS version: 12.0+

Client ID

The public OIDC client identifier for the identity provider application.
This must match the Client ID configured in Google, Azure AD, or Okta.

Client Secret

The secret associated with the OIDC client.
Some identity providers (like Google) return a Client Secret; others may not require one depending on app type.

Discovery URL

The OIDC metadata URL provided by the IdP.

Examples:

Redirect URI

The redirect URL required for returning authorization responses.
Defaults to:

https://127.0.0.1

Scopes

OIDC scopes that define what user attributes are returned (claims).
These typically include:

Examples:

openid profile email

Note: Some IdPs require additional scopes such as groups or user.read.

Should Set Google Access Type To Offline

This setting is specific to Google Workspace environments.

  • True: Ensures refresh tokens are requested correctly

  • False: Normal OIDC behavior applies

Minimum requirement: macOS 12.0+

Attribute Mapping

These fields map IdP user attributes to local macOS user properties.

Field

Description

Typical Value

Map First Name

OIDC claim for user’s given name

given_name

Map Last Name

OIDC claim for user’s family name

family_name

Map Full Name

Combined user name string

name

Map Full Username

Full username used for account mapping

name

Map Username

Local macOS account short name

name

Tip: For Azure AD, mapping may require using preferred_username or email.
For Okta, mapping may require using login or email.

Merging an existing local macOS account instead of creating a new account

In some deployments, users already have a local macOS account on the device before Apple Platform SSO is enabled (for example, when rolling out SSO to existing Macs). In this case, you may want the IdP login (Google SSO via Platform SSO) to merge with the existing local account instead of creating a brand‑new profile.

How the merge behavior works

When a user signs in at the macOS login window using their IdP credentials (for example, Google Workspace via Platform SSO), the user is typically presented with an option similar to:

  • Create New Account

  • Or continue with an existing local account

Behavior:

  • If the user selects “Create New Account”
    → Platform SSO will create a new local macOS user profile, separate from any existing local account.

  • If the user does not select “Create New Account” and instead signs in against the existing local user
    → Platform SSO will merge/bind the IdP account to the existing local macOS account.
    In testing, the Google SSO account was successfully merged into the existing local account when “Create New Account” was not chosen.

This helps organizations avoid duplicate user profiles when rolling out Platform SSO to machines that already have local users.

Recommended deployment pattern

For best results when you want to merge into an existing account:

  1. Enroll the device and create the local account first

    • Ensure the user’s primary macOS account already exists on the device (and is the one they should continue using).

  2. Configure Apple Platform SSO & Platform SSO in Swif

    • Confirm attribute mappings are correct so the IdP user matches the intended local account.

  3. At first SSO login, instruct users clearly

    • Tell users not to choose “Create New Account” at the Platform SSO prompt if they already have a local account on the Mac.

    • Instead, they should:

      • Select or enter their existing local user account, and

      • Complete sign‑in with their IdP credentials (e.g., Google Workspace).

  4. Verify the merge

    • After login, confirm:

      • The same local macOS account is used.

      • Platform SSO/Google SSO now successfully signs into that existing account on subsequent logins.

Known limitations and stability notes

  • Feature availability:

    • Platform SSO supports merging an IdP account into an existing local user when “Create New Account” is not selected.

    • No separate Swif UI feature is required for this; it is handled by Platform SSO at login.

  • Stability caveat (black screen issue):

    • During earlier testing, there were cases where Platform SSO could present a black screen or fail to render the login window correctly when using this flow.

    • These issues were tracked separately and may depend on specific Platform SSO/macOS versions.

    • If you encounter black screens or a missing login window:

      • Test on the latest supported macOS and Swif client version.

      • Collect Platform SSO logs as described in the “Troubleshooting: Collecting Platform SSO Logs” section below.

      • Share the logs and details (macOS version, exact flow, time of occurrence) with Swif Support.

When to prefer a new account instead of merge

Consider using “Create New Account” instead of merging when:

  • You are deploying entirely new, freshly provisioned Macs where no previous local account should be preserved.

  • You want to enforce a clean, IdP‑only-login model without legacy local accounts.

  • There is a risk that existing local accounts use email addresses or usernames that do not match your IdP schema, and you’d rather avoid ambiguity.

Controlling the “Switch Login Window” Option (FileVault & Security)

On macOS 12.0+ devices, Apple’s login window can show a “Switch login window” option that lets users switch between different login experiences (for example, from the Platform SSO window back to the classic local login window).

For organizations enforcing macOS login via Platform SSO, this can create a security gap because users might bypass the SSO login screen and sign in with a local account instead.

To address this, Swif includes a policy setting:

Disable Switch Login Window Button

When enabled, this setting:

  • Prevents the “Switch login window” control from being shown or used at the macOS login screen.

  • Helps enforce Platform SSO as the primary/only login method on managed devices.

  • Is applied via the same Platform SSO / macOS login profile generated by Swif.

Minimum requirement: macOS 12.0+ and a Platform SSO profile deployed from Swif.

When you should enable this setting

Enable Disable Switch Login Window Button if:

  • You want users to always authenticate via Platform SSO (Google Workspace, Microsoft Entra ID, Okta) at login.

  • You are concerned that users might bypass SSO and log in with cached or local passwords.

  • Your compliance or security model requires IdP‑only login for FileVault‑protected devices.

In these scenarios, removing the ability to switch login windows helps ensure users cannot quietly fall back to local accounts.

Important lockout considerations

If you disable the “Switch login window” button on devices, keep in mind:

  • If IdP or internet access is unavailable, users may not be able to log in if:

    • They do not have a valid cached SSO session, and

    • You have prevented them from switching to the local login window.

  • This may temporarily render the device inaccessible until connectivity or IdP availability is restored, or the restrictive profile is removed.

Best practices:

  • Test this configuration on a small pilot group before broad rollout.

  • Make sure admins understand how to remove or relax the policy (for example, via recovery workflows, safe mode, or by re‑pushing a profile that re‑enables the switch option).

  • Communicate clearly to end users that Platform SSO is their primary login path and what to do if they see errors at the login window.

How to configure in Swif

  1. In the Swif admin console, go to your Apple Platform SSO Policy (macOS login settings).

  2. Locate the toggle: Disable Switch Login Window Button.

  3. Set the value:

    • ON (true) – the “Switch login window” option is disabled/hidden at the macOS login screen.

    • OFF (false / unset) – the login window behaves normally, and users can still switch login windows.

  4. Save the policy and re‑push the updated profile to your target macOS device group.

  5. Restart a test device to confirm the behavior at the login window.

Expected end‑user behavior

  • With the toggle OFF (default / not enforced):

    • Users see the standard macOS “Switch login window” control.

    • They can move between the Platform SSO login experience and the classic local login window.

  • With the toggle ON:

    • The “Switch login window” option is hidden or disabled at the login screen.

    • Users stay in the Platform SSO login flow and cannot switch back to a local‑only login window.

    • Platform SSO should continue to function normally (prompting for IdP credentials, handling token‑based login, etc.).

If you encounter issues after enabling this setting (such as unexpected behavior at the login window), follow the steps in the Troubleshooting: Collecting Platform SSO Logs section below and share the logs with Swif Support.

Best Practices

  • Use Platform SSO instead of local passwords for improved security and compliance.

  • Ensure attribute mappings match your IdP schema to prevent login issues.

  • Test with a single macOS device before organization-wide deployment.

  • Combine this policy with the Apple Login Window Policy for maximum control of login behavior.

  • You can combine it with Apple User Authorization Policy to prevent local user password changes. Learn more at Mac Platform SSO & Apple User Authorization Policy.

How to Configure (High-Level)

  1. Create an OIDC app in Google, Azure AD, or Okta.

  2. Add the Redirect URI (https://127.0.0.1) in your IdP.

  3. Obtain the following from your IdP:

    • Client ID

    • Client Secret

    • Discovery URL

  4. Map your OIDC attributes using the policy fields.

  5. In Swif.ai, create a new Apple Platform SSO Policy and enter the required values.

  6. Assign the policy to devices or device groups.

  7. Restart the macOS device to begin SSO onboarding.

Compliance & Security Benefits

  • Eliminates local password storage

  • Ensures centralized identity enforcement

  • Reduces phishing risks

  • Enables SSO across macOS and cloud applications

  • Supports SOC 2, ISO 27001, and modern Zero Trust frameworks

Here is a section you can add to https://help.swif.ai/en/articles/12839068-apple-platform-sso-policy under a Troubleshooting / Collect Logs section.

Troubleshooting: Collecting Platform SSO Logs

If Apple Platform SSO or the login window authentication is not working as expected, Swif Support may ask you to collect Platform SSO debug logs.

Follow the steps below to enable debug logging and capture the issue.

Step 1: Enable Platform SSO Debug Logging

Open Terminal and run the following command:

sudo defaults write /Library/Preferences/com.twocanoes.xcreds showDebug -bool true

This enables detailed debug logging for Platform SSO.

Step 2: Reboot the Device

Restart the Mac so that the new debug logging setting is applied during the login process.

Step 3: Reproduce the Issue

After the reboot:

  1. Attempt the login or authentication process where the issue occurs.

  2. Trigger the problem (for example, login failure, missing Platform SSO login window, or authentication errors).

Step 4: Log in to the Device

Log in normally to the device so the logs can be saved.

Step 5: Collect the Log Files

After logging in, retrieve the following log files:

/tmp/xcreds/xcreds.log 
~/Library/Logs/xcreds.log

These files contain detailed debug information about the Platform SSO authentication process.

Step 6: Send Logs to Swif Support

Provide the collected logs to Swif Support for analysis.

Include:

  • The two log files

  • The macOS version

  • The time when the issue occurred

  • A brief description of the issue

Disable Debug Logging (Optional)

After troubleshooting is complete, you can disable debug logging with:

sudo defaults write /Library/Preferences/com.twocanoes.xcreds showDebug -bool false

This helps prevent excessive logging once the issue has been resolved.

Related Articles
Apple FileVault Policy
Enforcing Google SSO at macOS Login
Enforcing Okta SSO at macOS Login
Enforcing Azure AD SSO at macOS Login
Mac Platform SSO & Apple User Authorization Policy
Did this answer your question?