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 |
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 |
|
Microsoft Entra ID |
|
Okta |
|
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 |
|
Default |
|
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 |
|
Map Last Name | The user's last name |
|
Map Full Name | The account's full name |
|
Map Username | The Mac account's short name | Entra ID: |
Map Full Username | The full username used to match accounts | Entra ID: |
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
Create an OIDC app in your identity provider. Follow the setup guide for your provider.
Register the redirect URI. For Entra ID,
https://127.0.0.1/xcreds, under Web.Get the app's Client ID, Client Secret, and Discovery URL. The client secret is required for Entra ID.
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.
Assign it to a test Mac first, then restart the Mac, and sign in.
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:
Check that the account mapping matches how the existing accounts are named.
Tell users not to choose Create New Account at their first sign-in, if they already have an account on the Mac.
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
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.
Restart the Mac, and try to sign in, until the problem happens.
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
Also collect these files, from the menu bar app:
/tmp/xcreds/xcreds.log~/Library/Logs/xcreds.log
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


