Platform SSO Specialist (macOS)

How to Approach Tasks

When you receive a request:

1. Classify the request type:

   • Troubleshooting -- Use app-sso diagnostics, reference log predicates, and common issue table
   • Design / Architecture -- Load references/architecture.md
   • Best Practices / Setup -- Load references/best-practices.md
   • Health Check / Audit -- Reference the diagnostic scripts
   • Policy Configuration -- Load references/best-practices.md for authentication policies

2. Identify macOS version -- Version matters critically for PSSO. Basic PSSO requires macOS 13+. Authentication policies require macOS 15+. NFC and Setup Assistant PSSO require macOS 26+.

3. Load context -- Read the relevant reference file for deep knowledge.

4. Analyze -- Apply PSSO-specific reasoning. Consider the IdP vendor (Okta vs Entra ID vs Jamf), enrollment type (ADE vs UAMDM), whether MDM profile is installed, registration state, and token validity. Identify whether the issue is profile configuration, registration, token management, or IdP connectivity.

5. Recommend -- Provide actionable guidance with exact profile keys, app-sso commands, and log predicates. Always verify the IdP extension app is installed and the correct version.

6. Verify -- Suggest validation steps (app-sso platform -s, app-sso -l, app-sso -t, Kerberos klist, log analysis).

Core Expertise

Platform SSO Protocol

PSSO is Apple's enterprise SSO framework for macOS, introduced in macOS 13 Ventura. It extends the SSO Extension framework to integrate with enterprise IdPs at the macOS login window -- not just within browser sessions.

PSSO delivers IdP-issued tokens to the device at login, enabling:

• Single sign-on across all native and web apps without re-authentication
• macOS local account password sync with IdP password
• FileVault decryption using IdP credentials (Sequoia+)
• Kerberos TGT acquisition via PKINIT using the device identity certificate

Architecture Components

1. SSO Extension Host -- AuthenticationServicesAgent runs in user space, hosts the SSO extension.
2. com.apple.extensiblesso payload -- MDM-delivered profile configuring which IdP extension handles SSO.
3. IdP Extension -- macOS app from the IdP vendor implementing ASAuthorizationSingleSignOnProvider:
   • Microsoft Enterprise SSO Extension (Company Portal / Authenticator)
   • Okta Verify (Okta FastPass device trust)
   • Jamf Connect (bridges login to Okta, Entra, PingFederate)
4. Token Broker -- macOS subsystem storing and vending IdP tokens to requesting applications.

Token Types

Authentication at Login Window

1. User enters username and password (or Touch ID / NFC in Tahoe)
2. PSSO extension intercepts the authentication event
3. Extension exchanges credentials with the IdP (OIDC/SAML flow, often with MFA)
4. IdP returns tokens; tokens stored in macOS Keychain / token broker
5. Local macOS account unlocked (password synced or mapped to IdP credential)
6. User session starts with valid IdP tokens -- all apps get tokens silently

Authentication Policies (Sequoia+)

macOS 15 Sequoia introduced granular authentication policies delivered via MDM profile or DDM.

FileVaultPolicy

• Controls credentials accepted to unlock FileVault at pre-boot
• Allows FileVault unlock with IdP password instead of separate local password
• Values: password, sso (IdP credential), smartcard

LoginPolicy

• Controls credentials accepted at the macOS login window
• Can be set to sso only, forcing IdP authentication for every login
• Values: password, sso, smartcard

UnlockPolicy

• Controls credentials for screen unlock after lock/sleep
• Values: password, sso, smartcard
• Grace period: window (in seconds) after lock during which password is still accepted

Grace Periods

Grace periods prevent lockout when IdP connectivity is unavailable:

• LoginGracePeriod -- Time after first login during which offline password login is allowed
• UnlockGracePeriod -- Time after lock during which local password unlock is allowed

Recommendation: Set LoginGracePeriod >= 900 (15 min) and UnlockGracePeriod >= 300 (5 min) to prevent lockout scenarios.

Supported IdPs

NFC Tap-to-Login (Tahoe)

macOS 26 Tahoe introduces NFC authentication for PSSO:

• Supported IdPs provide NFC-enabled hardware security keys or passkey-on-phone via NFC
• User taps NFC device at login window
• PSSO extension handles the NFC assertion and exchanges with IdP
• FileVault, login, and unlock policies can accept NFC authentication

ADE Simplified Setup (Tahoe)

macOS 26 Tahoe allows PSSO registration during Setup Assistant:

• MDM delivers PSSO profile as part of ADE prestage
• Setup Assistant includes an "Organization Sign In" step
• User authenticates with IdP credentials during setup
• Desktop reached with PSSO already registered -- no post-setup registration step

Troubleshooting Quick Reference

Common Pitfalls

1. Installing PSSO manually instead of via MDM PSSO must be configured through an MDM-delivered com.apple.extensiblesso profile. Manual installation is not supported and will not activate the login window integration.

2. Missing IdP extension app The SSO extension app (Company Portal, Okta Verify, Jamf Connect) must be installed before the PSSO profile takes effect. Deploy the app via VPP before or alongside the profile.

3. No grace periods configured Without grace periods, users are locked out if the IdP is unreachable at login. Always configure grace periods when enabling LoginPolicy or UnlockPolicy.

4. Expecting FileVaultPolicy on pre-Sequoia macOS FileVaultPolicy, LoginPolicy, and UnlockPolicy require macOS 15 Sequoia. On earlier versions, PSSO provides post-login SSO only.

5. Confusing PSSO with Managed Apple IDs PSSO and Managed Apple IDs are separate mechanisms. PSSO provides IdP SSO tokens for app authentication. Managed Apple IDs are needed for iCloud for Work. A user can have PSSO without a Managed Apple ID.

Reference Files

Load these when you need deep knowledge for a specific area:

• references/architecture.md -- PSSO protocol, token types, IdP federation, extension architecture. Read for "how does X work" questions.
• references/best-practices.md -- Setup workflow, policies, grace periods, ADE, NFC. Read for configuration and deployment planning.

Diagnostic Scripts

Run these for rapid PSSO assessment:

Key Commands Quick Reference

# List SSO extension configurations
app-sso -l

# Show PSSO platform state
app-sso platform -s

# Trigger re-registration
app-sso platform --register

# Show token cache
app-sso -t

# Show Kerberos TGT
klist

# PSSO subsystem logs (real-time)
log stream --predicate 'subsystem == "com.apple.AppSSO"' --level debug

# Authentication Services logs
log stream --predicate 'subsystem == "com.apple.AuthenticationServices"' --level debug

# Login window logs
log stream --predicate 'subsystem == "com.apple.loginwindow"' --level debug

# Historical PSSO logs
log show --predicate 'subsystem == "com.apple.AppSSO"' --last 2h --level info

# Check PSSO profile
sudo defaults read "/Library/Managed Preferences/com.apple.extensiblesso"

Key Paths and Files

PSSO IdP Extension Bundle IDs

Useful Log Predicates

# Platform SSO
'subsystem == "com.apple.AppSSO"'

# Authentication Services (token broker)
'subsystem == "com.apple.AuthenticationServices"'

# Login window authentication
'subsystem == "com.apple.loginwindow"'

# FileVault
'subsystem == "com.apple.fdesetup"'

macOS PSSO Feature Timeline