Skip to main content

Apple Platform SSO Policy

The Apple Platform SSO Policy lets users sign in to their Macs with their Google Workspace, Microsoft Entra ID (Azure AD), or Okta account, instead of a separate local password. Swif creates or unlocks the matching Mac account at sign-in, and keeps its password in sync with the identity provider.

Identity provider

Setup guide

Google Workspace

Microsoft Entra ID (Azure AD)

Okta

This article covers every setting in the policy. For step-by-step setup, use the guide for your identity provider.


Requirements

Item

Details

Macs

macOS 12 or later, enrolled in Swif

Identity provider

Supports OpenID Connect (OIDC)

Admin access

In Swif, and in your identity provider

Google passkeys: two-step verification works, but passkeys, such as Touch ID, don't work at the Mac login window. The sign-in window can't use them while the Mac is starting up.


If FileVault is on

Platform SSO needs Disable automatic login if FileVault is enabled to be on. Otherwise, after the user unlocks FileVault, the Mac signs in automatically, and the Platform SSO sign-in window never appears.

  • Apple Platform SSO Policies created since March 2026 turn this on automatically. We recommend using the setting in this policy.

  • If an Apple Login Window Policy is also assigned to the same Macs, turn it on there too, so the two policies don't conflict.

What users see: after a restart, they unlock FileVault with their username and password. Then they see the Platform SSO sign-in window.


Settings

Identity provider

Setting

What to enter

Client ID

Your identity provider app's client ID

Client Secret

Your identity provider app's client secret. See Client Secret below.

Discovery URL

Your identity provider's OIDC metadata URL. See Discovery URL below.

Redirect URI

Where your identity provider sends users after sign-in. See Redirect URI below.

Scopes

The information requested about the user, such as openid profile email offline_access. offline_access lets the menu bar app check the user's sign-in in the background. It doesn't let users sign in offline.

Should Set Google Access Type To Offline

Google Workspace only. Turn it on, so Google provides refresh tokens.

Client Secret

Identity provider

Client Secret

Microsoft Entra ID

Required, when the redirect URI is registered under the Web platform, as in the Entra ID setup guide. Use the secret's Value, not its Secret ID.

Google Workspace

Provided with the OAuth client. Enter it.

Okta

Depends on the app type. See the Okta setup guide.

If the secret is missing, wrong, or expired, sign-in can stop partway, without an error. With Entra ID, it stops on Microsoft's "Stay signed in?" page.

Discovery URL

Identity provider

Discovery URL

Google Workspace

https://accounts.google.com/.well-known/openid-configuration

Microsoft Entra ID

https://login.microsoftonline.com/{tenantID}/v2.0/.well-known/openid-configuration

Okta

https://{company}.okta.com/.well-known/openid-configuration

For Entra ID, replace {tenantID} with your Directory (tenant) ID, from your app registration's Overview page. This URL works with single-tenant and multi-tenant apps. Don't use the common URL. It only works with multi-tenant apps.

Redirect URI

It must match the redirect URI registered in your identity provider exactly.

Identity provider

Redirect URI

Microsoft Entra ID

https://127.0.0.1/xcreds, registered under the Web platform only

Default

https://127.0.0.1

Account mapping

These settings choose which details from the identity provider become the Mac account's details.

Setting

Becomes

Typical value

Map First Name

The user's first name

given_name

Map Last Name

The user's last name

family_name

Map Full Name

The account's full name

name

Map Username

The Mac account's short name

Entra ID: preferred_username. Okta: login or email.

Map Full Username

The full username used to match accounts

Entra ID: preferred_username

Accounts and sign-in window

Setting

What it does

Create Admin User

On: new Mac accounts are administrators. Off: they're standard accounts.

Disable automatic login if FileVault is enabled

Keep it on if FileVault is on. See If FileVault is on.

Disable Switch Login Window Button

Hides the option to switch to the standard macOS sign-in window. See Require Platform SSO sign-in.

Sign-in window appearance (optional)

Setting

What it does

Login Window Background Image URL

A background image for the sign-in window, such as your company's branding. Use a public HTTPS link to a JPEG or PNG, at least 2560 × 1600 for Retina displays. If the link doesn't work, the default background is used.

Login Window Width

The sign-in window's width, in pixels. Start with 800–1000.

Login Window Height

The sign-in window's height, in pixels

Test the size on a laptop screen and a larger monitor. Don't put sensitive or user-specific information in the background image, since everyone sees it.


Set up Platform SSO

  1. Create an OIDC app in your identity provider. Follow the setup guide for your provider.

  2. Register the redirect URI. For Entra ID, https://127.0.0.1/xcreds, under Web.

  3. Get the app's Client ID, Client Secret, and Discovery URL. The client secret is required for Entra ID.

  4. Create the policy in Swif. Go to Device Management > Policies, select Create new policy > Configure a Policy, then Apple Platform SSO Policy. Enter the values, and set the account mapping.

  5. Assign it to a test Mac first, then restart the Mac, and sign in.

  6. Assign it to more Macs once sign-in works.

Restart Macs after every policy change. The sign-in window keeps its settings until the Mac restarts. If you change the policy, for example to add a new client secret, Macs keep using the old settings until they restart. Refresh in the sign-in window doesn't load the new ones.


Users who already have a Mac account

When you roll out Platform SSO to Macs that already have users, they can keep their existing account.

At their first Platform SSO sign-in, users see an option to Create New Account, or to use an existing account:

User chooses

Result

Their existing account

Their identity provider account is linked to the existing Mac account. They keep their files and settings.

Create New Account

A new, separate Mac account is created

To keep existing accounts:

  1. Check that the account mapping matches how the existing accounts are named.

  2. Tell users not to choose Create New Account at their first sign-in, if they already have an account on the Mac.

  3. After they sign in, check that they're in their usual account, and that later sign-ins use Platform SSO.

Choose Create New Account for new Macs, where there's no account to keep, or when existing account names don't match your identity provider's.

If the sign-in window is black, or doesn't appear, update macOS and Swif to the latest versions. If it still happens, collect logs, and contact Swif support. See Troubleshooting.


Require Platform SSO sign-in

macOS can show a button to switch to the standard sign-in window, where users can sign in with a local password. To require Platform SSO, turn on Disable Switch Login Window Button.

Setting

Users see

Off (default)

The switch button. They can sign in either way.

On

No switch button. They must sign in with Platform SSO.

Risk of being locked out. When the identity provider, or the internet, isn't available, users sign in with their Mac password, at the standard macOS login window. With the button hidden, they can't reach it, so they may not be able to sign in at all. The Mac may be unusable until the connection comes back, or the setting is removed. Test on a small group first, and make sure your admins know how to remove the setting.

Turn it on, save the policy, and restart a test Mac to check it.


Best practices

  • Test on one Mac before assigning the policy widely.

  • Check the account mapping, so accounts are created, and matched, with the right names.

  • Note when the client secret expires, create a new one before then, and restart Macs afterward.

  • Restart Macs after every policy change.

  • Stop users changing their local password, so it stays in sync with the identity provider. See Apple Platform SSO & Apple User Authorization Policy.


Troubleshooting

Sign-in stops partway, with no error

For example, Entra ID sign-in stops on "Stay signed in?", with loading dots. The identity provider accepted the password, but the Mac couldn't finish signing in.

  • Check the Client Secret. It's required for Entra ID, and must be the secret's Value, and not expired.

  • Check that the Redirect URI matches your identity provider exactly.

  • Restart the Mac after changing the policy.

If it still fails, follow Collect logs for Swif support below. The identity provider's error, such as Microsoft's AADSTS code, is only logged with detailed logging on.

Policy changes don't take effect

Restart the Mac. The sign-in window keeps its settings until the Mac restarts.

The Platform SSO sign-in window doesn't appear

  • If FileVault is on, check Disable automatic login if FileVault is enabled. See If FileVault is on.

  • Check that the policy is installed, in System Settings > General > Device Management.

  • Restart the Mac.

Collect logs for Swif support

  1. Turn on detailed logging. In Terminal, run:

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

    This only adds detail to the logs. It doesn't change how sign-in works, so it won't fix a sign-in problem.

  2. Restart the Mac, and try to sign in, until the problem happens.

  3. Sign in, then collect the sign-in window's log:

    log show --last 30m --predicate '(message contains "XCREDS" or message contains "OIDCLITE")' > ~/Desktop/xcreds-unified.log
  4. Also collect these files, from the menu bar app:

    • /tmp/xcreds/xcreds.log

    • ~/Library/Logs/xcreds.log

  5. Send them to Swif support, with the macOS version, when the problem happened, and what you saw.

When you're done, turn detailed logging off:

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


Related resources

Did this answer your question?