@capgo/capacitor-passkey

Passkeys for Capacitor with a browser-style WebAuthn shim.

Why this plugin

Most Capacitor apps already have browser-oriented passkey code based on:

await navigator.credentials.create({ publicKey: registrationOptions });
await navigator.credentials.get({ publicKey: requestOptions });

This plugin keeps that shape in a Capacitor app:

• It can auto-patch navigator.credentials.create/get for publicKey requests.
• It forwards the call to native passkey APIs on iOS and Android.
• It returns browser-like credential objects so existing code can keep working.
• It can auto-configure the generated iOS and Android host projects during cap sync/update.
• It also exposes direct JSON-safe methods when your backend already returns WebAuthn JSON.

What it does not do:

• It does not generate backend challenges for you.
• It does not remove the need for your website to host apple-app-site-association and assetlinks.json.
• It does not make Android native passkeys report your website's HTTPS origin to the server. On Android, normal apps use the app origin (android:apk-key-hash:...).

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/passkey/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-passkey` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-passkey

Browser-Like Setup

1. Configure the plugin once in capacitor.config.ts or capacitor.config.json.
2. Import the plugin from the standard package entrypoint.
3. Call CapacitorPasskey.autoShimWebAuthn() once during app bootstrap.
4. Keep your existing browser navigator.credentials.create/get code unchanged.

1. Configure capacitor.config.*

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'app.capgo.passkey.example',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorPasskey: {
      origin: 'https://signin.example.com',
      autoShim: true,
      domains: [
        'signin.example.com',
      ],
    },
  },
};

export default config;

Config keys:

• origin: the primary HTTPS relying-party origin for the app.
• domains: optional extra relying-party hostnames to wire natively during cap sync/update.
• autoShim: defaults to true. This only controls the native cap sync/update auto-configuration hook.

Then sync native projects:

bunx cap sync

During cap sync / cap update, the plugin automatically patches the generated host app:

• iOS: updates the entitlements file and wires CODE_SIGN_ENTITLEMENTS if needed.
• Android: injects asset_statements metadata and writes a generated string resource.

You do not need to manually edit the host project files every time.

2. Install The Shim During Bootstrap

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

That call reads plugins.CapacitorPasskey from the native Capacitor config and installs the WebAuthn shim explicitly.

3. Keep Existing WebAuthn Calls

After that bootstrap call, your browser-style code can stay the same:

const registration = await navigator.credentials.create({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rp: {
      id: 'signin.example.com',
      name: 'Example Inc',
    },
    user: {
      id: crypto.getRandomValues(new Uint8Array(32)),
      name: 'ada@example.com',
      displayName: 'Ada Lovelace',
    },
    pubKeyCredParams: [
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 },
    ],
  },
});

const authentication = await navigator.credentials.get({
  publicKey: {
    challenge: crypto.getRandomValues(new Uint8Array(32)),
    rpId: 'signin.example.com',
  },
});

What The Hook Configures

The plugin hook only patches the native host app files that Capacitor generates.

• It does not touch your app source code.
• It does not require you to permanently hand-edit Xcode or Android project files.
• It does not publish or generate the website association files for you.

Direct JSON-safe API

If your backend already returns PublicKeyCredentialCreationOptionsJSON or PublicKeyCredentialRequestOptionsJSON, you can call the plugin directly:

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

const registration = await CapacitorPasskey.createCredential({
  origin: 'https://signin.example.com',
  publicKey: registrationOptionsFromBackend,
});

const authentication = await CapacitorPasskey.getCredential({
  origin: 'https://signin.example.com',
  publicKey: requestOptionsFromBackend,
});

Website Files You Still Need

Passkeys only work when your app is associated with the same relying-party domain as your website.

iOS Website Association File

Host an apple-app-site-association file on your relying-party domain:

https://signin.example.com/.well-known/apple-app-site-association

Example:

{
  "webcredentials": {
    "apps": [
      "ABCDE12345.app.capgo.passkey.example"
    ]
  }
}

Notes:

• The file must be served with HTTP 200.
• Do not add a .json extension.
• The webcredentials domain must match the relying-party id you use for passkeys.
• The plugin hook writes the associated domains entitlement for you during cap sync/update.
• On iOS 17.4 and newer, the plugin uses the browser-style client-data API so the configured HTTPS origin is reflected in clientDataJSON.

Android Website Association File

Host a Digital Asset Links file at:

https://signin.example.com/.well-known/assetlinks.json

Example:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "app.capgo.passkey.example",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

• Use the same domain as your relying-party id.
• Include every signing certificate fingerprint you need, including debug builds if you test them.
• The plugin hook writes the asset_statements metadata and generated string resource for you during cap sync/update.
• Your website still needs to serve the actual assetlinks.json file.

Backend Notes

This plugin preserves the front-end WebAuthn API shape, but native platforms are not identical to a browser backend contract.

• iOS 17.4+ can encode the HTTPS origin you configure for the shim or direct API.
• Android Credential Manager does not act like a privileged browser app. The native response origin is tied to the Android app signature (android:apk-key-hash:...), not automatically to your website.
• With Digital Asset Links configured, Android can still use the same relying party and passkeys as your website. The part that differs is the literal clientDataJSON.origin string.
• If your server strictly validates clientDataJSON.origin, allow the Android app origin alongside your web origin.
• Your backend still needs the normal WebAuthn challenge lifecycle and signature verification.

Web Behavior

• On the web, the plugin forwards to the real browser WebAuthn API.
• On native Capacitor, the shim returns browser-like credential objects backed by native APIs.
• Call CapacitorPasskey.autoShimWebAuthn() once during bootstrap before using browser-style WebAuthn calls.
• Conditional mediation currently returns false.

Example App

The example-app/ folder demonstrates the auto-shim flow:

• example-app/capacitor.config.json configures the plugin.
• example-app/src/main.js imports CapacitorPasskey from @capgo/capacitor-passkey.
• example-app/src/main.js calls CapacitorPasskey.autoShimWebAuthn() during bootstrap.
• The actual registration and authentication still go through navigator.credentials.create/get.

API

shimWebAuthn(options?: ShimWebAuthnOptions | undefined) => void

getConfiguration() => Promise<PasskeyRuntimeConfiguration>

autoShimWebAuthn(options?: ShimWebAuthnOptions | undefined) => Promise<PasskeyRuntimeConfiguration>

createCredential(options: CreateCredentialOptions) => Promise<PasskeyRegistrationCredential>

getCredential(options: GetCredentialOptions) => Promise<PasskeyAuthenticationCredential>

isSupported() => Promise<PasskeySupportResult>

getPluginVersion() => Promise<PluginVersionResult>