electron-webauthn-mac

Native WebAuthn/Passkey support for Electron on macOS

Why This Addon?

The Web Authentication API navigator.credentials is the standard way to implement passkey authentication in web applications. However, in Electron applications running on macOS, this API is currently broken and non-functional due to platform-specific limitations (see electron/electron#24573).

This addon serves as a native implementation and polyfill for macOS, providing direct access to Apple's AuthenticationServices framework. It allows Electron applications to use passkey authentication on macOS while maintaining the option to use the standard Web Authentication API on other platforms.

Features

Platform & security key authenticators: Support for Touch ID, iCloud Keychain, cross-device QR pairing, and external FIDO2 keys
PRF extension: Derive symmetric keys from passkeys for client-side encryption (platform authenticators only)
LargeBlob extension: Store and retrieve arbitrary data on the authenticator (platform authenticators only)
System integration: Open macOS password manager directly from your Electron app
TypeScript support: Full type definitions included

Quick Start

1. Install the addon

npm install electron-webauthn-mac

2. Use the API

Basic example:

const webauthn = require('electron-webauthn-mac');

// Create a new passkey
async function registerUser() {
  try {
    const credential = await webauthn.createCredential({
      rpId: 'example.com', userId: 'user123', name: 'John', displayName: 'John Doe'
    });
    console.log('Created credential:', credential);
  } catch (error) {
    console.error('Registration failed:', error);
  }
}

// Authenticate with an existing passkey
async function authenticateUser() {
  try {
    const assertion = await webauthn.getCredential({ rpId: 'example.com' });
    console.log('Authentication successful:', assertion);
  } catch (error) {
    console.error('Authentication failed:', error);
  }
}

Tip

For cross-platform implementation, use the following pattern:

async function createPasskey(userId, userName, rpId) {
  if (process.platform === 'darwin') { // Use native addon on macOS
    const webauthn = require('electron-webauthn-mac');
    return await webauthn.createCredential({ ... });
  } else { // Use standard Web Authentication API on other platforms
    return await navigator.credentials.create({ ... });
  }
}

Note

TypeScript definitions are included. Import types directly:

import type {
  CreateCredentialOptions, GetCredentialOptions,
  RegistrationCredential, AssertionCredential
} from 'electron-webauthn-mac';

3. Configure the entitlements and domain association

Unlike browser-based WebAuthn, macOS requires your app to prove it has association with the domain used as rpId. Follow the steps in Configuring Entitlements and Domain Association to set this up. See Why is domain association required? for details.

4. Sign and run the app

Your Electron app must be code-signed to embed the entitlements from step 3 into the final .app bundle. Follow Provisioning Profile Setup to install the required provisioning profile. Running with npm start or electron . will launch the app, but passkey operations will fail because the unsigned process lacks an application identifier.

Use a tool like electron-builder to build a signed .app bundle. See the Example Electron App for a working configuration.

Example Electron App

The repository includes an example Electron application demonstrating the addon usage. It shows how to expose the addon from the main process to the renderer thread using Electron's contextBridge and ipcMain/ipcRenderer.

Important

Before running the example app, complete Configure the entitlements and domain association and Sign and run the app from Quick Start.

cd example-electron-app
npm install
npm run build:mac
open dist/mac-arm64/WebAuthnDemo.app

Configuring Entitlements and Domain Association

For WebAuthn to work with your domain (rpId), you must establish an association between your app and the domain. This is done by hosting an apple-app-site-association file on your server. See Apple's Associated Domains documentation for details.

1. Find Your Team ID and Bundle ID

Team ID: Found in Apple Developer Portal → Membership Details
Bundle ID: Your app's bundle identifier (e.g., com.yourcompany.yourapp)

2. Create the Association File

Host an associated domain file on your website (with a URL such as https://example.com/.well-known/apple-app-site-association) with the following content:

{
  "webcredentials": {
    "apps": [ "TEAM_ID.BUNDLE_ID" ] // Example: "A1B2C3D4E5.com.example.myapp"
  }
}

3. Confirm Server Requirements

The file must be:

Served over HTTPS (valid SSL certificate required)
Content-Type: application/json
Accessible without redirects at the exact path /.well-known/apple-app-site-association
No .json extension in the URL

4. Add Entitlements

In your Electron app's entitlements file, add:

<!-- Replace with your Team ID and Bundle ID -->
<key>com.apple.application-identifier</key>
<string>TEAM_ID.BUNDLE_ID</string>
<!-- Replace example.com with your domain name -->
<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:example.com</string>
</array>

Note

The domain in rpId must exactly match the domain in your associated domains entitlement and the domain hosting the apple-app-site-association file.

5. Verification

After deployment, you can verify your association file:

Visit https://example.com/.well-known/apple-app-site-association in a browser
Use an external validator like Branch.io AASA Validator or similar tools

Provisioning Profile Setup

Apps using the com.apple.developer.associated-domains entitlement require a provisioning profile installed on the development machine. Without it, macOS will reject the app at launch.

Creating the profile:

Go to Apple Developer Portal → Identifiers
Create or edit an App ID matching your bundle identifier
Enable the Associated Domains capability
Go to Profiles → create a macOS App Development profile for this App ID
Download the .provisionprofile file and double-click to install

`createCredential(options)`

Creates a new passkey credential using Touch ID, iCloud Keychain, or an external security key.

Options:

Property	Type	Required	Description
`rpId`	string	✅	Relying Party identifier (your domain, e.g., "example.com")
`userId`	string	✅	Stable user identifier (max 64 bytes recommended)
`name`	string	✅	User's name (used for both platform and security key authentication)
`displayName`	string	✅	User's display name (used for security key only)
`authenticators`	string[]		Which authenticator types to offer: `['platform', 'securityKey']` (default: both)
`excludeCredentials`	object[]		Existing credentials to prevent re-registration
`userVerification`	string		`'required'`, `'preferred'` (default), or `'discouraged'`
`attestation`	string		`'none'` (default), `'indirect'`, `'direct'`, or `'enterprise'`
`largeBlobRequired`	boolean		Require largeBlob support (macOS 14.0+, platform keys only)
`prf`	object		PRF extension request (macOS 15.0+, platform keys only)

Returns: Promise<RegistrationCredential>

Platform credential response (Touch ID / iCloud Keychain):

{
  type: "platform",
  credentialID: string,           // Base64-encoded credential ID
  attestationObject: string,      // Base64-encoded CBOR attestation
  clientDataJSON: string,         // Base64-encoded client data
  attachment?: string,            // "platform" or "crossPlatform" (macOS 13.5+)
  largeBlobSupported?: boolean,   // Whether largeBlob is supported (macOS 14.0+)
  prfEnabled?: boolean,           // Whether PRF extension is supported (macOS 15.0+)
  prfFirst?: string,              // Base64-encoded first PRF output (if requested)
  prfSecond?: string              // Base64-encoded second PRF output (if requested)
}

Security key credential response (external FIDO2 key):

{
  type: "securityKey",
  credentialID: string,           // Base64-encoded credential ID
  attestationObject: string,      // Base64-encoded CBOR attestation
  clientDataJSON: string,         // Base64-encoded client data
  transports?: string[]           // ["usb", "nfc", "ble", "internal", "hybrid"] (macOS 14.5+)
}

`getCredential(options)`

Authenticates a user using an existing passkey.

Options:

Property	Type	Required	Description
`rpId`	string	✅	Relying Party identifier (your domain)
`authenticators`	string[]		Which authenticator types to offer: `['platform', 'securityKey']` (default: both)
`allowCredentials`	object[]		Specific credentials to allow (if not set, discovers available)
`userVerification`	string		`'required'`, `'preferred'` (default), or `'discouraged'`
`largeBlobOperation`	object		`{ read: true }` or `{ write: "base64data" }` (macOS 14.0+, platform keys only)
`prf`	object		`{ eval: { first: "base64", second?: "base64" } }` (macOS 15.0+, platform keys only)

Returns: Promise<AssertionCredential>

Platform credential response (Touch ID / iCloud Keychain):

{
  type: "platform",
  userID: string,                 // Base64-encoded user handle
  credentialID: string,           // Base64-encoded credential ID
  authenticatorData: string,      // Base64-encoded authenticator data
  clientDataJSON: string,         // Base64-encoded client data
  signature: string,              // Base64-encoded signature
  attachment?: string,            // "platform" or "crossPlatform" (macOS 13.5+)
  largeBlobResult?: object,       // { type: 'read', data } or { type: 'write', success } (macOS 14.0+)
  prfEnabled?: boolean,           // Whether PRF extension was used (macOS 15.0+)
  prfFirst?: string,              // Base64-encoded first PRF output
  prfSecond?: string              // Base64-encoded second PRF output
}

Security key credential response (external FIDO2 key):

{
  type: "securityKey",
  userID: string,                 // Base64-encoded user handle
  credentialID: string,           // Base64-encoded credential ID
  authenticatorData: string,      // Base64-encoded authenticator data
  clientDataJSON: string,         // Base64-encoded client data
  signature: string,              // Base64-encoded signature
  appID?: boolean                 // Whether legacy FIDO U2F appID was used (macOS 14.5+)
}

`managePasswords()`

Opens the macOS system password manager (Settings → Passwords).

Parameters: None

Returns: void

macOS Platform Quirks

How It Works

The addon provides native WebAuthn/Passkey functionality using:

Swift: Core passkey logic using AuthenticationServices framework (src/PasskeyManager.swift)
Objective-C: Bridge between Swift and C++
C++: N-API bindings for Node.js integration
JavaScript/TypeScript: User-friendly wrapper API with full type definitions

Note

All credentials use ES256 algorithm (ECDSA P-256 with SHA-256) — the only algorithm supported by Apple's AuthenticationServices.

Why is domain association required?

Passkeys are tied to a specific domain (like example.com). When you authenticate with a passkey, macOS needs to verify that the app requesting access actually owns that domain — otherwise, a malicious app could impersonate your bank and steal your credentials.

Apple enforces this through a two-way trust mechanism:

Your server proves it trusts the app — by hosting a file at https://example.com/.well-known/apple-app-site-association that lists your app's bundle identifier
Your app declares which domain it represents — via the com.apple.developer.associated-domains entitlement embedded during code signing

When both sides match, macOS allows your app to create and use passkeys for that domain. Without this setup, passkey operations will fail with "Application is not associated with domain" errors.

Note

In browsers, localhost is exempt from domain verification for development convenience. Native macOS code has no such exception — domain association is always required, even for local testing. You'll need a real domain with HTTPS to develop and test passkey functionality with this addon.

Platform vs Security Key authenticators

Apple's AuthenticationServices framework distinguishes between two authenticator types (see Apple's documentation):

Type	What it is	Examples
Platform	Built-in or tightly integrated with the device	Touch ID, Face ID, iCloud Keychain, cross-device via QR code
Security Key	External FIDO2 hardware tokens	YubiKey, Titan Key, etc (via USB, NFC, or Bluetooth)

As of 2025, PRF and LargeBlob extensions are only available for platform authenticators.

Differences from Browser WebAuthn

This addon differs from the standard browser-based Web Authentication API (navigator.credentials) due to Apple's AuthenticationServices framework limitations:

Parameter	Browser WebAuthn	This Addon
`challenge`	Server-generated, passed to API	Auto-generated internally (32 bytes via `SecRandomCopyBytes`). Retrieve from `clientDataJSON` if needed.
`rp.name`	Human-readable RP name shown to user	Not supported — macOS shows `rpId` domain instead
`timeout`	Configurable operation timeout	Not supported — system manages timeouts internally
`pubKeyCredParams`	Multiple algorithms supported	ES256 only (hardcoded by Apple)
PRF, LargeBlob	Available on all authenticators	Platform authenticators only — see Platform vs Security Key

Troubleshooting

"The calling process does not have an application identifier. Make sure it is properly configured."

The app is not running as a signed .app bundle. Follow Sign and run the app to build and code-sign your application.

"Application is not associated with domain" or "No credentials available"

The rpId domain is not associated with your app. Follow Configuring Entitlements and Domain Association and verify that your Team ID and Bundle ID match in both the server-hosted file and your app's entitlements.

App builds but shows "could not be opened" alert on launch

Your app uses restricted entitlements (associated-domains) but no matching provisioning profile is installed. macOS blocks such apps with a generic "could not be opened" dialog (system logs show "No matching profile found"). Follow Provisioning Profile Setup to create and install a development profile for your bundle ID.

PRF or LargeBlob extensions are not working

These extensions are only supported for platform authenticators (Touch ID / iCloud Keychain), not security keys. Use authenticators: ['platform'] to restrict to platform keys when using these extensions.

Plugin Development

Prerequisites

macOS 13.0+ (Ventura or later)
Xcode 15+ with Command Line Tools (xcode-select --install)
Node.js 18+ with npm
Apple Developer account (for code signing)

Project Structure

electron-webauthn-mac/
├── src/                       # Swift/Objective-C/C++ source code
│   └── PasskeyManager.swift   # Core WebAuthn logic (used by addon and dev app)
├── js/                        # JavaScript wrapper + TypeScript definitions
├── include/                   # Header file
├── native/                    # Prebuilt .node binary (generated)
├── binding.gyp                # node-gyp build configuration
├── example-electron-app/      # Example Electron application
└── dev-mac-app/               # Native macOS dev app (Xcode project)

Building the Addon

npm install
npm run build

This compiles the Swift code, builds the native addon, and copies the .node binary to native/.

WebAuthn Playground (Development App)

For faster iteration during development, use the native macOS dev app:

open dev-mac-app/WebAuthnPlayground.xcodeproj
# Build and run in Xcode (⌘R)

Why a separate native app?

Building through Electron requires code signing and bundling — which is slow. The native app provides:

Instant iteration — build and run directly from Xcode in seconds
Full debugger access — set breakpoints in Swift code, inspect variables
API playground — quickly test new AuthenticationServices features
Shared codebase — both Electron example and Playground projects use the same PasskeyManager.swift from src/

The playground includes buttons for all WebAuthn operations: registration, authentication, PRF encryption/decryption, and largeBlob read/write.

Tip

When developing new features, prototype them in the playground first, then integrate into the Electron addon once verified.

Publishing

npm run build        # Builds and copies .node to native/
npm publish          # prepublishOnly runs build automatically

License

This project is released under the MIT License.

Made with ❤️ by the Vault12 Team

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.vscode		.vscode
dev-mac-app		dev-mac-app
example-electron-app		example-electron-app
include		include
js		js
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
binding.gyp		binding.gyp
package-lock.json		package-lock.json
package.json		package.json

License

vault12/electron-webauthn-mac

Folders and files

Latest commit

History

Repository files navigation

electron-webauthn-mac

Contents

Why This Addon?

Features

Quick Start

1. Install the addon

2. Use the API

3. Configure the entitlements and domain association

4. Sign and run the app

Example Electron App

Configuring Entitlements and Domain Association

1. Find Your Team ID and Bundle ID

2. Create the Association File

3. Confirm Server Requirements

4. Add Entitlements

5. Verification

Provisioning Profile Setup

API Reference

createCredential(options)

getCredential(options)

managePasswords()

macOS Platform Quirks

How It Works

Why is domain association required?

Platform vs Security Key authenticators

Differences from Browser WebAuthn

Troubleshooting

"The calling process does not have an application identifier. Make sure it is properly configured."

"Application is not associated with domain" or "No credentials available"

App builds but shows "could not be opened" alert on launch

PRF or LargeBlob extensions are not working

Plugin Development

Prerequisites

Project Structure

Building the Addon

WebAuthn Playground (Development App)

Publishing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors 2

Languages

`createCredential(options)`

`getCredential(options)`

`managePasswords()`