Virtneu Auth Docs

Embedded passkeys

Add same-page WebAuthn and native platform passkeys through your own backend and verified RP configuration.

SDK 0.7.0 is published on npm. It adds @virtneu/auth/browser, a framework-free browser client and optional DOM management panel, plus Swift AuthenticationServices and Android Credential Manager adapter sources. Use the matching API, tenant migration 0020_embedded_passkeys.sql and verified RP configuration; npm publication, production activation and physical-device acceptance have separate receipts. Published 0.6.0 does not acquire these additions. Hosted OIDC remains a separate integration option; embedded passkey ceremonies can stay inside your Web page or native app.

Configure a verified customer RP

Each App/environment has one embedded configuration: customer-owned RP domain, exact HTTPS Web origins, iOS Team/Bundle app IDs and Android package/signing-certificate hashes. Enable Passkeys in the tenant policy as well. Save a disabled configuration in Studio, generate the short-lived DNS TXT challenge, publish it on the customer's DNS, verify it, then enable the exact configuration. Security-field changes clear verification and disable the configuration. Explicit localhost is test-only and cannot include native apps.

Download the generated AASA and assetlinks.json and publish them on your RP domain. Generation does not deploy them or prove that Apple/Android has fetched them. Configure Apple Associated Domains with webcredentials:<rp> and matching Team/Bundle signing; configure Android Digital Asset Links with the actual release/Play signing certificate. The configured iOS app ID is not an App Attest proof, and Android credential origin is not Play Integrity verification.

Existing hosted credentials remain bound to the platform RP. Responses distinguish rp_id and binding_kind. Changing RP requires enrollment again after authenticating the existing account; it does not migrate private keys. Keep an existing recovery/login path until the new credential works.

Keep Auth tokens on the backend

Your backend uses server-owned client_context with beginPasskeyRegistration or beginEmbeddedPasskeyLogin. The browser or native app receives only {attempt_id,public_key}, then submits {attempt_id,response}. Service credentials, Auth sessions, flow tokens and continuation tokens never enter browser/App responses. Only your backend chooses origin, app identity and RP; never forward arbitrary client context.

The complete integration guide and repository examples/embedded-passkey-bff.ts contain the complete Fetch handler contract. Inject durable attempt/session adapters, protected opaque HttpOnly cookies, CSRF and rate limits. Attempt consumption compares live binding, purpose, generation and expected user atomically. Session finalization and logout/reset must share a transaction and retain issued-handle family guards so an in-flight response cannot resurrect a logged-out session.

import { BrowserPasskeyClient, mountPasskeyPanel } from '@virtneu/auth/browser';

const client = new BrowserPasskeyClient({
  basePath: '/auth/passkeys',
  csrfToken: () => getProtectedCsrfToken(),
});
const panel = mountPasskeyPanel(document.querySelector<HTMLElement>('#passkeys')!, client, {
  allowLogin: true,
  onReauthenticationRequired: () => showSameAccountSignIn(),
});
await panel.refresh();

Use this import only with the matching 0.7.0 SDK/package. The client permits only same-origin BFF paths, sends same-origin credentials with JSON/CSRF, rejects redirects and bounds response streams. Registration/login start only through explicit calls; optional conditional autofill depends on browser support. The panel exposes pending/error/cancel states, rename, removal confirmation and reauthentication events. Dispose it when unmounting.

Adding/removing a factor clears the customer's old session and requires the same account to authenticate again; rename preserves sessions. A 202 response carries an opaque continuation handle, next_step and methods, not {authenticated:true}. First enrollment cannot replace an existing factor. If verification or a mutation has an uncertain result, sign in again and read current state; do not automatically replay it.

Native integration and evidence

Swift sources use the real AuthenticationServices APIs for iOS16+/macOS13+. Android sources use the real AndroidX Credential Manager APIs and lifecycle cancellation. Both include public credential metadata and backend list/rename/delete forwarding; management does not open an OS ceremony. examples/embedded-passkey-native-bff.ts reuses the protected handler with fixed server-side iOS/Android context and a required customer API/anonymous-bootstrap caller guard. Native requests do not obtain identity merely by supplying a Web Origin or app ID. Preserve the opaque backend binding cookie jar across requests and keep every Auth token private on the backend.

Compilation and JSON tests are separate from OS ceremonies. Real biometrics, hardware keys, phone QR, credential synchronization, published association files, production activation and npm publication require their own evidence. No software-signed fixture establishes those results.

On this page