Macos Platform Sso

---
name: macos-platform-sso
description: "macOS Platform SSO (PSSO): enterprise IdP integration (Okta, Microsoft Entra ID, Jamf Connect), authentication policies, ADE simplified setup, NFC Tap-to-Login, and token management. Covers macOS 13 Ventura through macOS 26 Tahoe. Use when: \"Platform SSO\", \"PSSO\", \"Okta macOS\", \"Entra ID macOS\", \"macOS SSO\", \"login window SSO\", \"FileVaultPolicy\", \"LoginPolicy\", \"UnlockPolicy\", \"Tap to Login\", \"NFC login\", \"IdP macOS\". Do NOT use for Entra ID/Okta tenant-side IdP configuration — use the security plugin's IAM skills; this covers the macOS client-side PSSO extension only. Do NOT use for general MDM enrollment — use the `macos-mdm-deployment` skill."
license: MIT
---

# Platform SSO (macOS)

This skill covers macOS Platform SSO across macOS 13 Ventura, 14 Sonoma, 15 Sequoia, and 26 Tahoe. It provides deep knowledge of:

- PSSO protocol architecture: SSO Extension Host, token broker, `com.apple.extensiblesso` payload
- IdP integration: Microsoft Entra ID (Enterprise SSO Plugin), Okta Verify, Jamf Connect, Ping Identity
- Token types: OAuth 2.0 access tokens, refresh tokens, Kerberos TGTs via PKINIT, OIDC ID tokens
- Authentication policies (Sequoia+): FileVaultPolicy, LoginPolicy, UnlockPolicy, grace periods
- User registration flow: MDM profile delivery, registration prompts, Secure Enclave key binding
- ADE simplified setup (Tahoe): PSSO registration at Setup Assistant, zero-touch SSO
- NFC Tap-to-Login (Tahoe): NFC-enabled hardware security keys, passkey-on-phone via NFC
- ABM IdP federation: Managed Apple IDs, SCIM provisioning from Okta and Entra ID
- Token management: `app-sso` CLI, Kerberos TGT lifecycle, silent token renewal
- Smart card and PKINIT integration: CryptoTokenKit, Kerberos pre-authentication

When a question is version-specific, note the relevant differences. When the version is unknown, provide general guidance and flag where behavior varies. For general macOS administration, see the `macos` skill. For broader MDM enrollment, see the `macos-mdm-deployment` skill.

## How to Approach Tasks

Route by request type: **troubleshooting** → `app-sso` diagnostics, log predicates, and the common-issue table; **architecture** → `references/architecture.md`; **best practices/setup** → `references/best-practices.md`; **health check** → the diagnostic scripts; **policy configuration** → `references/best-practices.md`.

**Identify the macOS version first** — basic PSSO requires macOS 13+, authentication policies require macOS 15+, NFC and Setup Assistant PSSO require macOS 26+. Reason from the IdP vendor (Okta vs Entra ID vs Jamf), enrollment type (ADE vs UAMDM), MDM profile presence, registration state, and token validity to isolate whether the issue is profile configuration, registration, token management, or IdP connectivity. Always verify the IdP extension app is installed and at the correct version. Validate with `app-sso platform -s`, `app-sso -l`, `app-sso -t`, Kerberos `klist`, and 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
| Token | Protocol | Use |
|---|---|---|
| OAuth 2.0 Access Token | OAuth 2.0 / OIDC | Web app SSO, Microsoft 365 |
| Refresh Token | OAuth 2.0 | Silent token renewal |
| Kerberos TGT | Kerberos via PKINIT | On-premises AD resources |
| JWT (ID Token) | OIDC | Identity assertion |

#### 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

| IdP | Extension | Notes |
|---|---|---|
| Microsoft Entra ID | `com.microsoft.CompanyPortalMac.ssoextension` | Bundled with Company Portal |
| Okta | `com.okta.mobile.auth-client` | Okta FastPass device trust |
| Jamf Connect | `com.jamf.connect.login` | Bridges login to multiple IdPs |
| Ping Identity | PingFederate Extension | Enterprise customers |

### 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

| Symptom | Likely Cause | Resolution |
|---|---|---|
| "Register with organization" persists | Extension crash or keychain corruption | `app-sso platform --register` to re-register |
| SSO tokens not delivered to apps | Extension not matching URL patterns | Verify `URLs` array in PSSO profile covers auth domain |
| Login window still prompts local password | LoginPolicy not enabled or grace period active | Check `LoginPolicy.Enable = true`; verify macOS 15+ |
| FileVault not accepting IdP password | FileVaultPolicy not configured or token expired | Verify FileVaultPolicy in profile; re-register PSSO |
| IdP connectivity errors at login | Split DNS / VPN not active at login window | Ensure DNS for IdP domains works before login |
| NFC tap not working (Tahoe) | NFC policy not set or extension lacks NFC support | Verify extension version; check Tahoe-specific profile keys |
| "Account not found" in IdP | Managed Apple ID not provisioned or SCIM failure | Check SCIM logs in IdP; verify user in correct group |

## 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:

| Script | Purpose |
|---|---|
| `scripts/01-psso-status.sh` | Registration state, IdP connection, tokens, extension state |
| `scripts/02-auth-policy-audit.sh` | FileVault/Login/Unlock policies, grace periods, NFC, smart card |

## Key Commands Quick Reference

```bash
# 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

| Path | Purpose |
|---|---|
| `/Library/Managed Preferences/com.apple.extensiblesso` | PSSO MDM profile settings |
| `/Library/Managed Preferences/com.apple.loginwindow` | Login window managed prefs |
| `/Library/Managed Preferences/com.apple.security.smartcard` | Smart card enforcement |
| `/Applications/Company Portal.app` | Microsoft SSO extension host |
| `/Applications/Okta Verify.app` | Okta SSO extension host |
| `/Applications/Jamf Connect.app` | Jamf SSO extension host |

## PSSO IdP Extension Bundle IDs

| IdP | Extension Bundle ID | App Required |
|---|---|---|
| Microsoft Entra ID | `com.microsoft.CompanyPortalMac.ssoextension` | Company Portal |
| Okta | `com.okta.mobile.auth-client` | Okta Verify |
| Jamf Connect | `com.jamf.connect.login` | Jamf Connect |

## Useful Log Predicates

```bash
# 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

| Feature | First Available | Notes |
|---|---|---|
| Platform SSO | macOS 13 Ventura | Okta, Entra ID, Jamf Connect |
| PSSO expanded | macOS 14 Sonoma | Improved registration flow |
| PSSO Auth Policies | macOS 15 Sequoia | FileVaultPolicy, LoginPolicy, UnlockPolicy |
| PSSO at Setup Assistant | macOS 26 Tahoe | ADE + PSSO in one step |
| NFC Tap-to-Login | macOS 26 Tahoe | IdP extension must support NFC |
| MDM migration + PSSO | macOS 26 Tahoe | Re-registration after vendor migration |