Introduction
This is part six of a six part blog series on how to configure Apple Platform SSO using Omnissa Workspace ONE Unified Endpoint Management (UEM). Each part of the blog covers the various vendor configuration options and the series wraps up with a blog dedicated to troubleshooting. As each vendor continues to change their implementation these blogs will be updated.
Part 1 – What is Apple Platform SSO
Part 2 – How to configure Apple Platform SSO for Kerberos with Microsoft AD or Microsoft Entra
Part 3 – How to configure Apple Platform SSO with Microsoft EntraID
Part 4 – How to configure Apple Platform SSO with Okta Desktop Password Sync
Part 5 – How to configure Apple Platform SSO with Omnissa Access
Part 6 – Troubleshooting
Troubleshooting Platform SSO by hand means running a dozen Terminal commands, reading several log files and remembering what each answer means. That is slow, and it is easy to miss something. This page is now built around a diagnostic script that runs those checks for you, writes the evidence into one zip file, and starts the zip with a plain-English answer to the question that matters most:
Did Platform SSO registration succeed, and is it working the way it was designed to?
The page is organized in this order:
- Start here: run the script (about five minutes, one command)
- Read the result
- A decision guide, keyed to the script’s checks
- Manual checks that apply to every implementation
- Sections for each vendor: Microsoft Entra ID, Microsoft Kerberos, Okta and Omnissa Access and Hub
- A corrected command cheat sheet
Expect this page to be updated frequently, as we tend to learn more with every implementation of this technology.
Start here: run the script
The script is a single zsh file that runs on the affected Mac. Download it from the project’s GitHub page (link to be added). Its file name carries its version, for example pssodiagv312.zsh is version 3.1.2, and the same version is on the second line of the file.
What you need
- macOS 26 or 27, with the Mac enrolled in your MDM
- An administrator who can use
sudo - Full Disk Access for the Terminal app you run it from. If it is missing, the script stops and tells you how to grant it. Open System Settings > Privacy & Security > Full Disk Access, switch Terminal on, quit Terminal completely (Command-Q) and open it again.
- Someone logged in at the desktop, because registration and the Safari test are per user
Run it
chmod +x ./pssodiagv312.zsh
sudo ./pssodiagv312.zsh
It asks “Proceed?”, then works for about five minutes. Most of that time is sysdiagnose. The finished zip is written next to the script (or wherever you point --output-dir), and the zip file name ends with the result, for example PSSO-Diag-<hostname>-<timestamp>-NOT-REGISTERED.zip. The same answer is printed at the end of the run.
The best way to catch a problem
macOS keeps debug messages for the Platform SSO subsystem only briefly unless you ask it to persist them. If you can reproduce the problem, do this:
- Turn on persistent debug logging:
sudo ./pssodiagv312.zsh --debug-logging on(it asks first, changes the setting for thecom.apple.AppSSOsubsystem only, and exits) - Reproduce the problem (for the Microsoft extension, Microsoft also suggests turning on Turn on advanced logging in Company Portal > Settings)
- Run the script right after the attempt.
sudo ./pssodiagv312.zsh --tests-onlyis the fast version: no sysdiagnose, nohubcliarchive, a three hour log window - Turn the setting back:
sudo ./pssodiagv312.zsh --debug-logging off
Those are the same log settings Microsoft documents for its extension; the script just wraps them so nobody has to remember the syntax.
Useful options
| Option | What it does |
|---|---|
--tests-only |
Fast mode for use right after a failed attempt |
--test-url [url ...] |
Run only the Redirect URL network tests, then exit (see below). URLs after it are tested too |
--handoff-url <url> |
Also test, with a Safari test, whether a specific website is handed to the SSO extension (repeat up to 10 times) |
--kerberos-url <url> |
Kerberos web test: curl --negotiate as the logged-in user, then look for the service ticket (up to 3) |
--output-dir <path> |
Put the zip somewhere other than the script’s folder |
--debug-logging on|off |
Persist (or stop persisting) AppSSO debug logs; asks first |
--no-browser-test |
Skip the background Safari tests |
--skip-sysdiagnose |
Skip the slow sysdiagnose step |
--dry-run |
Show what it would do and collect nothing |
The zip contains account names, host names, device identifiers and a full sysdiagnose. Share it only through channels your organization allows, and never attach it to a public forum post.
The first thing it does: can the Mac reach the Redirect URLs?
Before it collects anything, the script tests the Redirect URLs in your SSO payload and shows each URL and its result as it goes. This catches the three most common network-side causes in seconds: a firewall or web filter blocking a URL, a URL missing from the payload (or with a typo), and a site that is simply offline.
Testing Microsoft Redirect URLs (the 3 that Microsoft requires)...
https://login.microsoftonline.com reachable (HTTP 200, 0.24 s)
https://login.microsoft.com reachable (HTTP 200, 0.28 s)
https://sts.windows.net NOT reachable - timed out (a firewall or proxy may be dropping the connection, or the site is offline)
What it tests depends on the vendor named in the payload:
- Microsoft: the three URLs Microsoft requires (
https://login.microsoftonline.com,https://login.microsoft.com,https://sts.windows.net) are reachable; any of the four optional sovereign-cloud URLs your payload includes are reachable; and the payload really includes the three required ones. - Okta: your org’s
/device-access/api/v1/nonce,/oauth2/v1/tokenand/v1/auth/device-signare reachable and in the payload. The org host, including a custom domain, is read from the payload. - Omnissa Hub:
https://<your Access tenant>/mpssois reachable and in the payload. - Apple’s associated-domain servers:
app-site-association.cdn-apple.comandapp-site-association.networking.appleare reachable. macOS validates every SSO domain through them, and Microsoft documents that they must not be blocked or TLS-inspected.
It then tests any additional URL the payload lists, and says “looks like a typo of …” when one nearly matches an expected URL. If a required URL fails during a full run, it asks whether to continue, so you can fix the network first. To run only these tests, for example right after a firewall change, use sudo ./pssodiagv312.zsh --test-url (add URLs after it to test those too). It needs sudo to read the profiles, but no Full Disk Access and no zip.
Read the result
Open the zip and read Apple_PSSO_Configuration.txt. The first lines answer the question:
RESULT: Platform SSO is NOT registered on this Mac.
The last registration attempt (11-10-2026 11:02:20 UTC) FAILED.
The result codes
| Result (and zip suffix) | What it means |
|---|---|
REGISTERED |
Device and user are registered, user state is Normal, and no automated check failed |
REGISTERED-WITH-FAILURES |
Registration works, but at least one check failed. Read the FAIL lines |
DEVICE-ONLY |
The Mac is registered but the user is not. The user still has to finish registration, or it failed |
NOT-REGISTERED |
No registration. The line under the result says why (a failed attempt, a prompt nobody answered, or no attempt at all) |
KERBEROS-ONLY |
The Mac does not use Platform SSO but has the Kerberos extension configured, for example an AD-bound Mac. The line under the result says whether the Kerberos checks passed, and the Platform SSO checks are skipped |
NO-PSSO |
No Platform SSO configuration, and no Kerberos extension, was found. Check that the profile is assigned and installed |
Below the result
- A PASS / WARN / FAIL / INFO / SKIP summary.
FAILis a real problem or evidence of one.WARNdeserves attention but is not necessarily wrong.INFOis context.SKIPmeans the check did not apply (for example, a user check on a Mac with no registered user). - A DIAGNOSIS section. For each failure pattern the script recognizes, three plain sentences: what it sees, what that means, and what to do.
- The list of every check, with the evidence behind each.
- The settings your SSO payload actually defines, one per line, with secrets hidden. This is how you answer “did the profile apply with the settings I think it should have?” without opening the profile by hand.
The checks are automated greps and probes. They are a starting point, not a verdict. Everything they read is in the zip so you can confirm it.
Where things are in the zip
| Folder | What is in it |
|---|---|
01-sysdiagnose |
Apple’s archive, untouched, plus a record of the exact command, time and SHA-256, so you can hand both to Apple Support |
02-psso-state |
app-sso state, the extension registration, local accounts |
03-mdm-payload |
The profiles MDM delivered, the install, update and removal events, and the MDM command and app install timeline |
04-psso-registration-logs |
The registration timeline, and the IdP extension’s own logs (Company Portal, Okta Verify) |
05-hub-logs |
Intelligent Hub logs |
06-validation |
The evidence behind the automated checks |
Inside every folder the files are numbered in the order to read them.
Decision guide
Find the check name from the script’s output in the first column.
| If you see | It usually means | What to do |
|---|---|---|
device-registration or user-registration FAIL |
Registration never completed | Read the line under RESULT:. If prompts were shown and never answered, the user must open the Platform SSO notification and sign in. Microsoft notes that if the sign-in dialog is closed, the user signs out and in again to bring the notification back |
DIAGNOSIS: MSAL -51116 “redirected to a non-https url” |
Something between the Mac and Microsoft answered the sign-in request, since Microsoft’s service does not redirect to plain http | Look at the network-agent lines (web filters, VPNs, proxies, security agents) and the signin-authorize line. Repeat registration with those products off or exempted |
redirect-url or redirect-url-payload FAIL |
A URL the payload needs cannot be reached from this Mac (this includes Apple’s two associated-domain servers; the reason is next to the URL: DNS, timeout, reset, TLS, HTTP error), or a URL the vendor requires is missing from the payload | For an unreachable URL, ask the network team to allow it, or check the vendor’s status page if it is offline. For a missing URL, add it to the URLs list in your MDM. Re-test with sudo ./pssodiagv312.zsh --test-url |
apple-cdn-tls FAIL |
Apple’s AASA servers are being TLS-inspected | Microsoft documents that app-site-association.cdn-apple.com and app-site-association.networking.apple must not be TLS-inspected. Exempt *.cdn-apple.com and *.networking.apple, then register again |
payload-foreign-domain FAIL |
Your profile lists, for this extension, a domain that belongs to another vendor (for example login.microsoftonline.com in a Hub profile). That domain’s AASA file lists only the other vendor’s apps, so macOS denies your extension |
Remove the domain from the URLs list and from the Associated Domains payload. Only the domain’s owner can authorize an extension for it, and a URL kept in your profile stays reserved, so the vendor’s own SSO profile could not use it |
domain-association, aasa-origin, aasa-cdn or a denied pair: |
macOS or the domain’s own AASA file does not authorize the extension for a domain | See Associated Domains. A missing profile entry can be added. A file on someone else’s domain cannot be changed |
extension-installed FAIL |
The profile names an extension macOS cannot find | Check the app (Company Portal, Okta Verify or Hub) is installed |
idp-nonce, idp-jwks or idp-token FAIL |
The identity provider’s Platform SSO endpoints do not answer from this network | Check DNS, the firewall and any proxy for that host |
clock-skew WARN or FAIL |
The Mac’s clock differs from Apple’s time server | Turn on automatic date and time |
payload-extension-identity, payload-auth-method, payload-urls-unique |
The installed profile and the Mac disagree | Compare the printed payload settings with the vendor’s documentation |
hub-allow-list or hub-authorization WARN |
Microsoft’s extension turned the Hub app away | See Omnissa Access and Hub |
registration-without-profile or local-account-psso-link WARN |
Leftover Platform SSO state after a profile removal | See How do you turn off PSSO? |
kerberos-* WARN or FAIL |
A Kerberos problem | See Microsoft Kerberos |
okta-* WARN or FAIL |
The Okta profile differs from Okta’s documented profile | See Okta |
mdm-setup-gap WARN |
After the Mac enrolled in Setup Assistant, the MDM server sent nothing for 10 minutes or more | See Setup Assistant is stuck after enrollment |
INFO appsso-debug-logging NOT persisted |
The logs may lack detail of an earlier attempt | Use --debug-logging on, reproduce, run again |
Universal Troubleshooting Tips
The script covers items 3 to 5 automatically. They are listed here because you sometimes need to check by hand.
- Setup Assistant (Simplified Setup) keys: check your UEM console version first.
The Extensible SSO profile has keys that turn on Platform SSO during Setup Assistant: Enable registration during setup and Enable first user during setup. Apple says to use the registration key when Platform SSO is configured before enrollment, and Okta documents turning it on for macOS 26 or later.
There is a reported problem on specific Workspace ONE UEM console versions (2410, 2506 and 2509): with these keys turned on, a macOS 26 device can stall in Setup Assistant, because the console is missing code that the new keys need. Omnissa is working on it (reference Jira MACOS-6620 with Omnissa support).
So the safe guidance is to confirm your console version before you turn these keys on, and test on a spare device first. In our own testing, Macs on macOS 27.2 enrolled through Automated Device Enrollment with both keys turned on completed Platform SSO registration in Setup Assistant. I have not tied that result to a console version, so it does not say anything about the console versions above.
If you use custom settings, leave both keys out until you have confirmed support. The script reports which of these keys your profile sets (
payload-setup-assistant) and whether the Mac is ADE-enrolled, since the keys do nothing on a Mac that is not.
- A key being in Apple’s payload does not mean your identity provider supports it. Apple defines many Platform SSO settings, and its documentation says of the authentication method that the SSO extension also needs to support it. For example, Platform SSO has keys to create users and assign groups, and Microsoft’s extension does not use them. Unsupported keys should be ignored, but it is sometimes best to remove them. The script prints every setting your payload defines, so you can compare against the vendor’s page.
- Does the SSO extension profile exist on the device? Check System Settings > General > Device Management (Privacy & Security > Profiles on older macOS), or let the script list the installed SSO payloads (
sso-payloads). Verify the URLs or Hosts match what you configured. Apple requires every URL, and every Host, to be unique across all installed Extensible SSO payloads. - Is the SSO extension registered with macOS?
The extension identifiers to look for:pluginkit -m -v -p com.apple.AppSSO.idp-extensioncom.microsoft.CompanyPortalMac.ssoextension(Microsoft),com.okta.mobile.auth-service-extension(Okta Verify) andcom.ws1.hub.mac.SSOExtension(Omnissa Hub). The script’s check isextension-installed. - Did the device complete registration?
On macOS 26 and 27 the output is JSON-style. Look forapp-sso platform -s"registrationCompleted" : true, and for the user"state" : "POUserStateNormal (0)". The login configuration should not be empty. (Older macOS versions printed this differently, asDevice Configuration.registrationCompleted = true.) The script’s checks aredevice-registration,user-registration,device-keys,user-secure-enclave-keyandsso-token. - Which Kerberos tickets exist? Run
klistas the logged-in user, with nosuand nosudo. Kerberos tickets are kept in each user’s own credential cache, so running the command as root shows root’s cache, which is usually empty. Standard users can runklistand see their own tickets.
Time zones in the logs
A Mac in Setup Assistant starts on a default time zone and later switches to the right one, so the clock times inside one log file can jump by whole hours. Do not compare raw clock times across that point. Some slices carry a per-line UTC offset, so each line is unambiguous. Others, such as the AppSSO slice, carry the Mac’s clock with no offset at all. Everything the script writes itself is UTC, its timelines convert every line to UTC, and the Times: lines at the top of the findings (and the timezone-change check) give the exact moment the offset changed. If you read a compact-style slice by hand, use that moment to decide which offset applies to each line.
Setup Assistant is stuck after enrollment
If a Mac sits in Setup Assistant after it enrolls and never reaches the desktop, start with what the MDM server has sent. With Await Configuration on, the ADE enrollment profile carries AwaitDeviceConfigured, and Setup Assistant holds the Mac until the MDM server sends a DeviceConfigured command. Apple’s documentation describes no timeout for that wait, so a Mac can wait for hours. The wait is on the server’s side, and Platform SSO is not involved until its profile arrives.
The script records this in the MDM command timeline in the findings. It lists every command the Mac received, its result, the profile each install was, and the apps the installer actually installed, by name, all in one time order. After an enrollment made in Setup Assistant it marks any quiet stretch of five minutes or more, marks the SSO profile, and says whether the SSO profile arrived before or after DeviceConfigured. The mdm-setup-gap check warns at ten minutes. Read it like this:
- One long gap before the first command, or before the profiles: the server did not send. Open the device’s command queue in your MDM console for those times and see what was pending.
- An app installed twice before Setup Assistant was released: the timeline flags it (“Installed more than once before Setup Assistant was released”). In the one hung enrollment we captured, Company Portal was installed twice about fifteen minutes apart, before any profile arrived, and the SSO profile showed up only after the ADE profile was saved with Workspace ONE UEM’s “PSSO during Setup Assistant” setting turned off. UEM also re-sends Company Portal on healthy enrollments, but in those it came after
DeviceConfigured(the apps installed after the release), so a repeat on its own is not the problem. What matters is the order and that the profiles were late. The timeline also shows which installer package each MDM-managed install ran and whether a server app-install command came just before it. Two runs of the same package, the second with no command before it, means the Mac ran it on its own; a command before each means the server sent it twice. Which UEM assignment sent it, a bootstrap package or an app assignment, is something to check in the console’s command queue for the device. - The SSO profile after
DeviceConfigured: the MDM had already released Setup Assistant before the profile arrived, so the Platform SSO panes would not run there. NotNowanswers: the Mac told the server to retry later (mdm-notnow).- A long app download or install can explain a gap, so check what was running before blaming the server.
Note that “PSSO during Setup Assistant” is a setting on the UEM ADE profile (Omnissa documentation). It is separate from the EnableRegistrationDuringSetup key inside the SSO payload, so a profile can still show those keys as true after you turn the ADE setting off, and Setup Assistant will still show its Platform SSO panes once the profile arrives.
Associated Domains: what they are for
Apple’s Platform SSO design needs proof of who owns the sign-in traffic an extension redirects. That proof has two halves, and both must agree:
- the device must know the app is associated with the domain, and
- the domain’s own
apple-app-site-association(AASA) file, as Apple’s CDN serves it, must list the app.
That is why Microsoft’s Company Portal needs no Associated Domains payload from you: on the Macs we checked, swcutil already showed Microsoft’s sign-in domains approved for it with no payload installed, so the association evidently ships with the app. An extension used by many customers with different tenant domains, such as Hub, needs those entries delivered by MDM. It is also why adding Microsoft’s or Okta’s domain to Hub’s entry in the payload cannot make Hub act for those domains: their AASA files list their own apps (Microsoft’s file lists Microsoft apps, Okta’s lists Okta’s), not Hub. The script checks both halves for every pair of app and domain in your payload (pair:APP@DOMAIN), and --handoff-url shows whether a specific website is handed to the extension.
What websites can trigger the extension?
For a Redirect-type extension, the profile’s URLs list is the set of URL prefixes macOS hands to it, and Apple matches the scheme and host and requires the URLs to be unique. Vendors differ in what they list:
- Microsoft lists its sign-in hosts (
login.microsoftonline.comand others), so any app or site that signs in through Entra is handed to the extension. - Okta lists its device endpoints (the nonce, token and device-sign paths).
- Omnissa Hub’s profile lists the tenant’s Platform SSO endpoint (a path under
/mpsso). Only URLs under that prefix are handed to Hub’s extension.
To see what your own profile does, run sudo ./pssodiagv312.zsh --handoff-url <the site>: it reports whether the URL is covered by the payload, what swcutil and the AASA say, and whether Safari actually hands the page to an extension (and which one). “Handed to the extension” means macOS routed the request; it does not by itself prove the page signed you in.
How do you turn off PSSO?
The answer depends on which IdP plugin is in use, and whether the authentication method is Secure Enclave or Password Sync. Secure Enclave is relatively simple to remove, but Password Sync is trickier. In most instances it is faster to wipe the device than to remove PSSO manually, and removing the MDM profile alone does not reset things.
For Microsoft’s extension, the supported way to remove a registration is Company Portal > Preferences > Deregister.
If you want to try a manual removal, this is one set of steps:
- Run
app-sso platform -sand note the current configuration (or keep the script’s zip as the “before” snapshot). - In UEM remove the PSSO profile from the device. On the Mac, confirm it is gone from System Settings > General > Device Management (older macOS: Privacy & Security > Profiles).
- Make sure all SSO extension profiles, including credential extensions such as the Kerberos extension, are removed. If any remain, macOS will not remove the registration.
- Use MDM to uninstall the IdP plugin app. This is not an option for Omnissa Hub, so only do it for Okta or Microsoft.
- Restart the device.
- Run
app-sso platform -sagain and compare with step 1. If it worked, most of the records are deleted. - If a device record exists in the IdP, now is a good time to delete it.
With Password Sync it gets a bit dicey, because the password in the IdP has been applied to the macOS user, so after removal it is the IdP password that must be supplied, not the original macOS password.
If the local password is no longer accepted at the lock screen, the user account may have been modified. Log in as a different account and, only after checking that the first command shows a PlatformSSO: entry, run:
dscl . read /Users/username AltSecurityIdentities | grep 'PlatformSSO:'
dscl . delete /Users/username AltSecurityIdentities "$( dscl . read /Users/username AltSecurityIdentities | grep 'PlatformSSO:' | awk '{ print $NF }' )"
dscl . delete /Users/username dsAttrTypeNative:PlatformSSOUniqueIdentifier
Delete that single AltSecurityIdentities value as shown; deleting the whole attribute will break the user account. These commands change the account, so use them only as a last resort. The script never runs them. It does check, read-only, whether each local account still carries a Platform SSO link (local-account-psso-link) and whether a registration exists with no profile installed (registration-without-profile), which tells you whether removal left anything behind.
As stated at the beginning of this tip, wiping the device and starting over is usually faster and less error prone.
Troubleshooting Microsoft Entra ID
Platform SSO with Microsoft’s Company Portal extension is only supported for Microsoft Entra join deployments; Microsoft has no plans to support hybrid join.
- In the configuration samples in the earlier parts of this series, PSSO is enabled for all installed apps and for specific websites such as
https://login.microsoftonline.com. When troubleshooting, start with Safari, then the Microsoft 365 apps, then third-party apps, to isolate where the problem is. Begin by asking: did the SSO profile apply, and did it apply with the settings you think it should have? The script’s payload settings listing answers the second question. - A successful PSSO registration creates a device record in the Entra admin center under Devices > All devices, and Microsoft says a PSSO-registered Mac shows the join type Microsoft Entra joined (a Mac that is only registered shows Microsoft Entra registered). This is not the same registration that happens with Microsoft Conditional Access. If things seem askew, ask your Entra administrator (and your Intune administrator, if applicable) whether anything in Entra or Intune could conflict.
- Check the extension’s own log. The script copies the Company Portal SSO extension’s log files into
04-psso-registration-logs/idp-extension-files. When a registration fails, macOS logs the reason as<private>, but this log usually has the real one. For example,Failed to get Deviceless Primary Refresh tokenwithMSIDErrorDomain Code=-51116and “The server has redirected to a non-https url” points at the network path, not at the profile. In one engagement the only difference between registrations that failed this way and one that worked was whether a web-content-filter system extension was running on the Mac; that is a correlation, not a proof, but it is why the script lists the web filters, VPNs and proxies that are running, and when they started relative to the registration attempt (network-agent). - Extra Company Portal logging. Open Company Portal > Settings and enable Turn on advanced logging. To persist AppSSO debug messages, run these as separate commands (or use the script’s
--debug-logging on):sudo log config --mode "level:debug,persist:debug" --subsystem "com.apple.AppSSO" # reproduce the problem, then capture the data sudo sysdiagnose # when you are finished, put logging back to the default sudo log config --reset --subsystem "com.apple.AppSSO" - The sign-in test. Run
app-sso platform -s, then open Safari and browse tohttps://login.microsoftonline.com. The first time you may be prompted. Log out of macOS and back in and try again; this time PSSO should sign you in with no prompts. The script automates the first half:sudo ./pssodiagv312.zsh --handoff-url https://login.microsoftonline.com/shows whether the page is handed to the Company Portal extension. - Network path. Platform SSO needs Apple’s AASA servers and Microsoft’s sign-in endpoints reachable without interception. The script checks that Apple’s two AASA hosts present Apple’s certificate (
apple-cdn-tls), that Microsoft’s OpenID and sign-in endpoints answer over https without a redirect to http (signin-openid,signin-authorize), and that the nonce, JWKS and token endpoints respond (idp-*). Microsoft’s troubleshooting page also documents a reset for Apple’s association cache if associations look stuck. - Hub on the same Mac. If Intelligent Hub is installed alongside Company Portal, Microsoft’s extension may match Hub’s own sign-in requests to Microsoft and turn them away unless Hub is on its allow list. The script reports this as
hub-allow-listandhub-authorization, with the extension and error code involved. Microsoft’s settings that govern it areAppAllowList,AppPrefixAllowList,AppBlockListandEnable_SSO_On_All_ManagedApps(which admits only MDM-managed apps). - Additional documentation from Microsoft:
Account name mapping. For
TokenToUserMapping > AccountName, Microsoft documents two choices:com.apple.PlatformSSO.AccountShortName(the UPN prefix becomes the local account short name, Microsoft’s recommended choice) andpreferred_username. The script does not judge your choice; it reports which one is defined (payload-account-name).
Troubleshooting Microsoft Kerberos
Does it work? Here is a summary of the areas to focus on:
| Focus Area | Expected Behavior |
|---|---|
| Platform SSO | Auto login to Entra, Entra apps SSO works |
| Kerberos SSO | TGT acquired on demand, renewals automatic |
| Browsers | Safari and Chrome send SPNEGO to AD and Entra ID apps |
| Apps | Microsoft Office apps installed on the device sign in without prompting |
| Ticket cache | Cloud TGT, AD TGT and service tickets all exist |
| Reliability | Does it work after a reboot? If the Wi-Fi network changes? How are renewals handled? |
| Failure behavior | Predictable 401s and recoverable login paths |
The script runs the Kerberos checks whenever a Kerberos extension payload, a Kerberos status in the PSSO state, or --kerberos-url is present. A Mac that uses only the Kerberos extension (no Platform SSO) gets the result KERBEROS-ONLY, and the Platform SSO checks are skipped.
- Confirm the profile installed. System Settings > General > Device Management, then open the profile and confirm the payloads match what you configured with no “invalid configuration” messages.
- Platform SSO status.
app-sso platform -s. On macOS 26 and 27 expect"registrationCompleted" : true,"state" : "POUserStateNormal (0)"and a login type of Secure Enclave key (or the key type you configured). The PSSO state also reports the Kerberos status per realm:importSuccessful,failedToConnectandexchangeRequired. The script reads these askerberos-status:<realm>: afailedToConnectof true means the Mac could not reach the Kerberos service for that realm. - Which Kerberos tickets exist? Run
klistas the logged-in user (not withsuorsudo; see the universal tips). Look for a TGT from the configured provider, for examplekrbtgt/KERBEROS.MICROSOFTONLINE.COM@KERBEROS.MICROSOFTONLINE.COM. The script lists the TGTs and their issued and expiry times (kerberos-tgt-times). - Test ticket retrieval. Requesting a service ticket means first requesting it, downloading it, and having macOS register that it exists for the next round of authentication. The easiest way to test is to pick an internal website that requires Kerberos.
- Automated:
sudo ./pssodiagv312.zsh --kerberos-url https://intranet.example.com/. The script runscurl --negotiateas the logged-in user, then looks inklistfor a service ticket forHTTP/<host>. A 200 plus a service ticket is a pass; a 401 with no ticket points at no TGT, a host missing from the Kerberos extension’s Hosts, a wrong SPN, or an unreachable domain controller. - By hand: open Safari, enable Settings > Advanced > Show features for web developers, then Develop > Web Inspector, and load the URL. If you get a 401, look in the Headers tab for
Authorization: Negotiate <token>. With IIS a 200 OK is what you should see. Then runklist: there should be two entries, a TGT for Entra ID and a service ticket matchingHTTP/for the site. If IIS is the backend, its W3SVC logs should show the user asDOMAINNAME\USERNAMEwith no errors.
- Automated:
- Test TGT renewal. Lock the screen, wait two minutes, unlock and run
klistas the user. The TGTs should show a new issued time and there should have been no prompts. - When Kerberos cannot reach the domain controller, new tickets cannot be issued and internal sites return 401. For an AD realm the script looks up the domain controllers in DNS (
_kerberos._tcp.<realm>) and tests TCP port 88 (kerberos-dc:<realm>); off the corporate network or VPN a failure here is expected. The cloud realmKERBEROS.MICROSOFTONLINE.COMhas no domain controller to reach, because Entra issues the ticket. - Realm and host settings.
app-sso -llists the realms configured through the Kerberos extension, andapp-sso -i <REALM>shows one realm’s details; the script prints its useful fields askerberos-realm-info(last Kerberos login, password last changed, AD site, and whether the extension reports the network as available). This applies to realms configured through the Kerberos extension, not to the cloud realmKERBEROS.MICROSOFTONLINE.COM, whereapp-sso -ihas nothing to report. (There is noapp-sso configuration listcommand.) For the Kerberos extension (a Credential-type payload) Apple requires everyHostsentry to be unique across all installed Extensible SSO payloads, and ignores theRealmsetting for Redirect payloads. The script checks for duplicate Hosts (kerberos-hosts-unique) and prints the Kerberos extension’s realm and host count (kerberos-extension-config).
Troubleshooting Okta Desktop Password Sync
The script applies its Okta checks whenever Okta’s extension (com.okta.mobile.auth-service-extension) is the active one.
- Check the profile against Okta’s documentation. Okta documents a profile with three parts, and the script checks each (
okta-*):- an SSO extension payload (Redirect type, team
B7F62B65BN) whose URLs include the nonce, token and device-sign paths of your org:/device-access/api/v1/nonce,/oauth2/v1/tokenand/v1/auth/device-sign(okta-urls) - an Associated Domains payload with both app identifiers,
B7F62B65BN.com.okta.mobileandB7F62B65BN.com.okta.mobile.auth-service-extension, each withauthsrv:<your org>.okta.com(okta-associated-domains) - two preference payloads, one for
com.okta.mobileand one forcom.okta.mobile.auth-service-extension, carryingOktaVerify.OrgUrl,OktaVerify.PasswordSyncClientIDandPlatformSSO.ProtocolVersionset to2.0(okta-preference-domains,okta-org-url,okta-protocol-version)
- an SSO extension payload (Redirect type, team
- Use the same org URL in every entry, and use your custom domain if you have one. Okta’s setup page puts your org URL (for example
https://customerorg.okta.com) in the profile, tells you to use your custom domain URL if you have configured one, and to use the same org URL each time. A custom domain is when you replace the Okta domain name with your own, for examplelogin.example.com; Okta says the originalcustomerorg.okta.comdomain keeps working after you create one. So the host in the SSO payload’s URLs, theauthsrv:entry in Associated Domains andOktaVerify.OrgUrlshould all be the same. The script reads that host from the payload and checks it is consistent (okta-org-url), accepts a custom domain, and tests the host’s three Okta URLs in its Redirect URL tests. - Okta Verify’s logs. Okta Verify stores its logs in the user’s home directory, in
~/Library/Group Containers/B7F62B65BN.group.okta.macverify.shared/Logs. The script copies the log files from the last three days into04-psso-registration-logs/idp-extension-files/okta-verifyautomatically. To copy them by hand:
Also look for log entries labeledcp -R "$HOME/Library/Group Containers/B7F62B65BN.group.okta.macverify.shared/Logs" "$HOME/Downloads/OktaVerifyLogs_$(date +%Y_%m_%d-%H%M)"com.okta.mobile.auth-service-extension. - Okta’s documentation: configure PSSO using Workspace ONE and configure PSSO using a generic MDM (Secure Enclave).
Troubleshooting Omnissa Access and Hub
- Omnissa has published troubleshooting documentation that covers both Access and Platform SSO in general.
- Hub’s logs. The script collects the
hubclilog archive and the Hub unified-log slices (05-hub-logs).--tests-onlyskips the slow archive and keeps the unified-log slice. - Hub’s health check. Hub logs a Platform SSO health evaluation (healthy or unhealthy, with the attributes it checked). The script lists each evaluation and warns if Hub reports unhealthy after macOS shows the Mac as registered. If there is no evaluation in the log window the script says so as a note (“a gap in the evidence, not a pass”); it is not an error.
- What the Hub extension handles. The Safari test in the script reports which extension receives a payload URL. With the Hub extension active, a URL under the tenant’s
/mpssopath is handed tocom.ws1.hub.mac.SSOExtension, andswcutilapproves the tenant domain for Hub’s app identifier (S2ZMFGQM93.com.ws1.hub.mac). See Associated Domains for why Microsoft’s and Okta’s domains cannot be added to Hub’s entry. If the Hub profile also lists a Microsoft sign-in domain, the script reports onepayload-foreign-domainfinding that explains why it cannot work and what to remove. - Hub with Microsoft’s extension on the same Mac. See the Entra section: the
hub-allow-listandhub-authorizationchecks tell you whether Microsoft’s extension is rejecting Hub’s own requests, and which settings control it.
Command cheat sheet
The app-sso options below were checked against the help text on macOS 26.7.3; the log commands are the ones Microsoft documents. Run klist as the logged-in user.
| Task | Command |
|---|---|
| Is the extension registered? | pluginkit -m -v -p com.apple.AppSSO.idp-extension |
| Platform SSO state | app-sso platform -s |
| Sample Platform SSO messages for the current configuration | app-sso platform -m |
| Kerberos realms | app-sso -l (details: app-sso -i REALM) |
| Kerberos tickets | klist |
| Installed profiles with their settings | sudo profiles show -all -output stdout-xml |
| What macOS decided about an associated domain | sudo swcutil show |
| Persist AppSSO debug logs | sudo log config --mode "level:debug,persist:debug" --subsystem "com.apple.AppSSO" |
| Stop persisting them | sudo log config --reset --subsystem "com.apple.AppSSO" |
| Capture a sysdiagnose | sudo sysdiagnose |
| All of the above and more, with a summary | sudo ./pssodiagv312.zsh |
Next Steps
Thank you for visiting! If you wish to revisit the previous blogs in the series, here are the links:
Part 1 – What is Apple Platform SSO
Part 2 – How to configure Apple Platform SSO for Kerberos with Microsoft AD or Microsoft Entra
Part 3 – How to configure Apple Platform SSO with Microsoft EntraID
Part 4 – How to configure Apple Platform SSO with Okta Desktop Password Sync
Part 5 – How to configure Apple Platform SSO with Omnissa Access
Part 6 – Troubleshooting
5 thoughts on “How to Troubleshoot Apple Platform SSO”