capacitor-webauthn

Passkey and WebAuthn registration and authentication for Capacitor 8 on iOS and Android.

This plugin is maintained against the Capacitor 8 plugin baseline. It uses Android Credential Manager on Android and AuthenticationServices on iOS.

Platform Support

• Capacitor: @capacitor/core 8+
• Android plugin baseline: minSdkVersion 24, compileSdkVersion 36, targetSdkVersion 36
• Android passkey runtime availability: Android 9 / API 28+
• iOS plugin baseline: deployment target 15.0
• iOS passkey runtime availability: iOS 16.0+

Install

npm install capacitor-webauthn
npx cap sync

Native Requirements

• Android passkeys require Digital Asset Links for the relying-party domain. Host assetlinks.json at https://<domain>/.well-known/assetlinks.json and include delegate_permission/common.get_login_creds.
• iOS passkeys require the Associated Domains entitlement for the relying-party domain, for example webcredentials:example.com.
• Native registration should include rp.id, and native authentication should include rpId. These values must match the website domain your server uses for WebAuthn/passkeys.
• isWebAuthnAvailable() reports whether the device can run the native passkey flow. It does not guarantee that the user already has a credential for your relying party.

Implementation Notes

• Android includes androidx.credentials:credentials-play-services-auth so passkeys work through Credential Manager on supported older Android releases as well.
• iOS returns WebAuthn base64url fields and omits userHandle when the authenticator does not provide one.

API

• isWebAuthnAvailable()
• startRegistration(...)
• startAuthentication(...)
• Interfaces
• Type Aliases

isWebAuthnAvailable()

isWebAuthnAvailable() => Promise<{ value: boolean; }>

Returns: Promise<{ value: boolean; }>

startRegistration(...)

startRegistration(publicKeyCredentialCreationOptionsJSON: PublicKeyCredentialCreationOptionsJSON) => Promise<RegistrationResponseJSON>

| Param | Type | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | publicKeyCredentialCreationOptionsJSON | PublicKeyCredentialCreationOptionsJSON |

Returns: Promise<RegistrationResponseJSON>

startAuthentication(...)

startAuthentication(requestOptionsJSON: PublicKeyCredentialRequestOptionsJSON) => Promise<AuthenticationResponseJSON>

| Param | Type | | ------------------------ | ------------------------------------------------------------------------------------------------------- | | requestOptionsJSON | PublicKeyCredentialRequestOptionsJSON |

Returns: Promise<AuthenticationResponseJSON>

Interfaces

RegistrationResponseJSON

| Prop | Type | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | | id | Base64URLString | | rawId | Base64URLString | | response | AuthenticatorAttestationResponseJSON | | authenticatorAttachment | AuthenticatorAttachment | | clientExtensionResults | AuthenticationExtensionsClientOutputs | | type | PublicKeyCredentialType |

AuthenticatorAttestationResponseJSON

| Prop | Type | | ------------------------ | --------------------------------------------------------------------------- | | clientDataJSON | Base64URLString | | attestationObject | Base64URLString | | authenticatorData | Base64URLString | | transports | AuthenticatorTransportFuture[] | | publicKeyAlgorithm | COSEAlgorithmIdentifier | | publicKey | Base64URLString |

AuthenticationExtensionsClientOutputs

| Prop | Type | | ---------------------- | --------------------------------------------------------------------------------- | | appid | boolean | | credProps | CredentialPropertiesOutput | | hmacCreateSecret | boolean |

CredentialPropertiesOutput

| Prop | Type | | -------- | -------------------- | | rk | boolean |

PublicKeyCredentialCreationOptionsJSON

| Prop | Type | | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | rp | PublicKeyCredentialRpEntity | | user | PublicKeyCredentialUserEntityJSON | | challenge | Base64URLString | | pubKeyCredParams | PublicKeyCredentialParameters[] | | timeout | number | | excludeCredentials | PublicKeyCredentialDescriptorJSON[] | | authenticatorSelection | AuthenticatorSelectionCriteria | | attestation | AttestationConveyancePreference | | extensions | AuthenticationExtensionsClientInputs |

PublicKeyCredentialRpEntity

| Prop | Type | | ---------- | ------------------- | | id | string | | name | string |

PublicKeyCredentialUserEntityJSON

| Prop | Type | | ----------------- | ----------------------------------------------------------- | | id | Base64URLString | | name | string | | displayName | string |

PublicKeyCredentialParameters

| Prop | Type | | ---------- | --------------------------------------------------------------------------- | | alg | COSEAlgorithmIdentifier | | type | PublicKeyCredentialType |

PublicKeyCredentialDescriptorJSON

| Prop | Type | | ---------------- | --------------------------------------------------------------------------- | | id | Base64URLString | | type | PublicKeyCredentialType | | transports | AuthenticatorTransportFuture[] |

AuthenticatorSelectionCriteria

| Prop | Type | | ----------------------------- | ----------------------------------------------------------------------------------- | | authenticatorAttachment | AuthenticatorAttachment | | requireResidentKey | boolean | | residentKey | ResidentKeyRequirement | | userVerification | UserVerificationRequirement |

AuthenticationExtensionsClientInputs

| Prop | Type | | ---------------------- | -------------------- | | appid | string | | credProps | boolean | | hmacCreateSecret | boolean |

AuthenticationResponseJSON

| Prop | Type | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | | id | Base64URLString | | rawId | Base64URLString | | response | AuthenticatorAssertionResponseJSON | | authenticatorAttachment | AuthenticatorAttachment | | clientExtensionResults | AuthenticationExtensionsClientOutputs | | type | PublicKeyCredentialType |

AuthenticatorAssertionResponseJSON

| Prop | Type | | ----------------------- | ----------------------------------------------------------- | | clientDataJSON | Base64URLString | | authenticatorData | Base64URLString | | signature | Base64URLString | | userHandle | Base64URLString |

PublicKeyCredentialRequestOptionsJSON

| Prop | Type | | ---------------------- | ----------------------------------------------------------------------------------------------------- | | challenge | Base64URLString | | timeout | number | | rpId | string | | allowCredentials | PublicKeyCredentialDescriptorJSON[] | | userVerification | UserVerificationRequirement | | extensions | AuthenticationExtensionsClientInputs |

Type Aliases

Base64URLString

string

AuthenticatorTransportFuture

'ble' | 'cable' | 'hybrid' | 'internal' | 'nfc' | 'smart-card' | 'usb'

COSEAlgorithmIdentifier

number

AuthenticatorAttachment

'cross-platform' | 'platform'

PublicKeyCredentialType

'public-key'

ResidentKeyRequirement

'discouraged' | 'preferred' | 'required'

UserVerificationRequirement

'discouraged' | 'preferred' | 'required'

AttestationConveyancePreference

'direct' | 'enterprise' | 'indirect' | 'none'