configureWebAuthn
Configures platform authenticators for the Web Authentication API (navigator.credentials.create() / navigator.credentials.get()). Until this is called, PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() resolves to false and platform-authenticator requests are not serviced.
When touchID is provided, WebAuthn credentials are stored in the macOS keychain and bound to this device's Secure Enclave. Electron automatically generates and persists a per-session metadata secret so that credentials created in one partition are not visible to another.
When platformPasskeys is true, passkey operations use Apple's ASAuthorizationController which delegates to the system's configured Credential Provider Extensions. This enables the same passkey experience as Safari — credentials are available across all devices signed into the same account. Unlike Touch ID credentials, platform passkeys are stored by the credential provider and scoped to the relying party, not to Electron: they are shared across all session partitions and with any other app or browser associated with the same domain. Platform passkeys cannot serve cross-origin (iframe) requests; those requests are left to the other available authenticators (Touch ID supports iframes) and a warning is logged to the DevTools console. The prf and largeBlob WebAuthn extensions are not currently supported by this authenticator — prf inputs are ignored, and a create() call with largeBlob: { support: 'required' } fails.
With the matching entitlements in your app's entitlements.plist:
For platform passkeys, your app needs the Associated Domains entitlement plus an application identifier, both in the same entitlements.plist:
Listing these entitlements is not sufficient on its own — unlike most entitlements, com.apple.developer.associated-domains is provisioning-profile backed. For platform passkeys to work, all of the following must hold:
In the Apple Developer portal, your App ID (
com.example.app) has the Associated Domains capability enabled, and you have created a provisioning profile for that App ID.That provisioning profile is embedded in the built app bundle at
Contents/embedded.provisionprofile. This is what authorizes the associated-domains entitlement at runtime; without an embedded profile macOS silently ignores thewebcredentialsassociation and the request fails. (Xcode and@electron/osx-signembed the profile for you; if you sign manually, copy it into the bundle before signing.)The app is signed (ad-hoc / unsigned builds do not qualify). Both distribution and development signing work — for development builds, use the developer-mode path described below.
com.apple.application-identifiermatches the profile's App ID. Without it,ASAuthorizationControllerfails with "The calling process does not have an application identifier" — this isASAuthorizationErrorcode 1004.The relying party's domain (
example.comabove) serves a validapple-app-site-associationfile over HTTPS at/.well-known/apple-app-site-associationcontaining awebcredentialsentry whoseappsarray lists this app's<TEAM_ID>.<BUNDLE_ID>.The relying party ID of each request matches that associated domain.
If these aren't satisfied, ASAuthorizationController fails before it can present the passkey sheet. The request surfaces to the page as a bare NotAllowedError with no further detail (Electron logs an explanatory message to the DevTools console on this path). Because the association is domain-based, platform passkeys always require a real associated domain and its AASA file — there is no localhost rpId escape hatch as there is in browsers.
To test against your domain with a development-signed build (before shipping a distribution profile), append ?mode=developer to the entitlement value and enable developer mode on the machine with swcutil developer-mode -e true. This makes macOS fetch the AASA directly from the domain — bypassing Apple's CDN cache — and honor the association for a development-signed app. You still need the embedded development provisioning profile described above:
!NOTE Because the request is fulfilled by the system credential provider (not a browser), the
clientDataJSONreturned to the page reportsorigin: "https://<rpId>"— the associated domain — rather than the page's own origin. Relying-party servers that enforce a strictexpectedOriginallowlist must includehttps://<rpId>for verification to succeed. This also means the relying party cannot distinguish which subdomain of the associated domain initiated the ceremony.
!NOTE Touch ID WebAuthn credentials are device-bound and are not synced via iCloud Keychain. They are only available on Macs with a Secure Enclave (Apple silicon, or Intel Macs with a T2 chip).