passkeys.dev logo passkeys.dev logo
  • Docs 
  • Device Support 
  • About 
  •  
  •  
  •  
  •  
Docs
  • Intro
    • What are passkeys?
  • Use Cases
    • Bootstrapping
    • Reauthentication
  • Advanced
    • Related Origin Requests
  • Tools & Libraries
    • Libraries
    • Test & Demo Sites
  • Reference
    • Android
    • iOS & iPadOS
    • Chrome OS
    • macOS
    • Windows
    • Known Issues
    • Specifications
    • Terms
  • Intro
    • What are passkeys?
  • Use Cases
    • Bootstrapping
    • Reauthentication
  • Advanced
    • Related Origin Requests
  • Tools & Libraries
    • Libraries
    • Test & Demo Sites
  • Reference
    • Android
    • iOS & iPadOS
    • Chrome OS
    • macOS
    • Windows
    • Known Issues
    • Specifications
    • Terms

macOS

Share via
passkeys.dev
Link copied to clipboard

Resources for passkeys in Apple macOS

On this page
Overview   Platform Notes   Cross-Device Authentication   Legacy Credentials   WebViews   User Verification Behavior   Resources  
 

Local Authenticator

(create and use passkeys from the local device)
 

External Authenticator

(create and use passkeys from another device)

Overview  

The platform authenticator in macOS Ventura (13) has the following capabilities:

  • creating and using passkeys saved to Apple Passwords
  • creating and using passkeys on/from another device, such as:
    • an iPhone or iPad signed in to a different Apple Account, using FIDO Cross-Device Authentication
    • an Android device, using FIDO Cross-Device Authentication
    • a FIDO2 security key1

1 On macOS, user verification methods (device PIN, biometric, etc) must already be configured on the security key prior to credential creation

Platform Notes  

Cross-Device Authentication  

macOS does not currently support persistent linking of external authenticators for Cross-Device Authentication at the operating system level.

Persistent linking is available between Android devices (authenticator) and Chrome and Edge (clients) on macOS.

When an authenticator is not persistently linked, a QR code must be scanned on every use.

Legacy Credentials  

WebAuthn credentials created using the platform authenticator in macOS Monterey (12) and earlier will not be converted to passkeys but will remain available for the lifetime of the device.

To replace a legacy platform credential with a passkey, start a credential registration ceremony and pass the same user handle (user.id) in the request. macOS will overwrite the legacy credential with a new passkey that will be saved to Apple Passwords.

WebViews  

Embedded WebViews  

WKWebView is the embedded WebView (EWV) on macOS. Embedded WebViews allow the calling app full control over the embedded web session, including modifying and intercepting requests, so many web platform features are limited in these contexts.

NOTE:

Embedded WebViews run in the context of the calling app, meaning only passkeys for the linked web domain (RP ID) can be created or used for sign in.

Said differently, only use EWV when sign in is handled by your own service (non-federated). When supporting multiple identity providers, System WebView should be used (see below).

WKWebView docs @ Apple Developer  

System WebViews  

ASWebAuthenticationSession is the System WebView (SWV) on macOS for authentication flows. The user’s default web browser will be invoked, allowing any supported Web Platform features, including WebAuthn, for the ASWebAuthenticationSession instance.

Sites loaded in ASWebAuthenticationSession are isolated from the calling app and run in the context of the top level site, just like in a full browser instance. This means that sign in flows on third party domains, such as a federated identity provider, can use passkeys for signing in.

ASWebAuthenticationSession docs @ Apple Developer  

User Verification Behavior  

On macOS, the user must set up a local system password. Enabling iCloud Keychain and setting up Touch ID are optional.

Safari on macOS 14  

  • When iCloud Keychain is not enabled and Touch ID is not configured on macOS:
    • The behavior for userVerification='required' is:
      • macOS asks the user to enable iCloud Keychain on passkey creation. Since user verification fails locally at this point, the server does not receive a credential.
      • On passkey authentication, macOS asks the user to enter the local system password or use Touch ID (if configured).
    • The behavior on userVerification='preferred' is:
      • macOS asks the user to enable iCloud Keychain on passkey creation. Since user verification fails locally at this point, the server does not receive a credential.
      • On passkey authentication:
        • If Touch ID is not configured, macOS skips user verification and returns the UV flag as false.
        • If Touch ID is configured, macOS asks for user verification with Touch ID and returns the UV flag as true.
    • Calling PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() always returns true.
  • When iCloud Keychain is enabled, but Touch ID is not configured on macOS or not available on the device (e.g. laptop lid is closed):
    • userVerification='required' asks the user to enter the local system password on both passkey creation and authentication. Since they fail locally if Touch ID setup fails, the server can always expect the UV flag to be true.
    • userVerification='preferred' skips user verification both on passkey creation and authentication. The UV flag is always false.
    • Calling PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() always returns true.

Chrome 120 with iCloud Keychain on macOS 14  

  • When iCloud Keychain is not enabled and Touch ID is not configured on macOS:
    • The behavior on userVerification='required':
      • macOS asks the user to enable iCloud Keychain on passkey creation. The UV flag sent to the server depends on the fallback user verification result.
      • On passkey authentication, macOS asks the user to enter the system password or use Touch ID (if configured). When user verification succeeds, it returns a credential with the UV flag as true, otherwise it fails locally.
    • The behavior on userVerification='preferred':
      • macOS asks the user to enable iCloud Keychain on passkey creation. The UV flag sent to the server depends on the fallback user verification result.
      • On passkey authentication, it skips user verification immediately and returns a credential with the UV flag as false.
        • If Touch ID is configured, macOS asks for user verification with Touch ID.The UV flag sent to the server depends on the fallback user verification result.
    • Calling PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() always returns true.
  • When iCloud Keychain is enabled, but Touch ID is not configured on macOS or not available on the device (e.g. laptop lid is closed):
    • userVerification='required' asks for the system password on both passkey creation and passkey authentication. Since they fail locally if user verification fails, the server can always expect the UV flag to be true.
    • userVerification='preferred' skips user verification and returns the UV flag as false for both passkey creation and passkey authentication.
    • Calling PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() always returns true.

Resources  

  • Apple landing page for passkeys
  • About the security of passkeys
  • Supporting passkeys
  • Supporting device-bound passkeys on security keys
  • Sample Code
Last Updated: May 14, 2025
On this page:
Overview   Platform Notes   Cross-Device Authentication   Legacy Credentials   WebViews   User Verification Behavior   Resources  
passkeys.dev
passkeys.dev
This site is brought to you by members of the W3C WebAuthn Community Adoption Group and the FIDO Alliance.
CC BY-NC-ND 4.0 | Privacy Policy
 
Links
Docs 
About 
Device Support 
Resources
Passkey Central 
Dev Discussions 
FIDO Alliance 
Tools
Client Feature Detect 
WebAuthn Response Decoder 
passkeys.dev
Code copied to clipboard