# Add PasskeyBase passkeys to an existing application You are a coding agent adding **PasskeyBase** to the project you are working in. Read this whole guide before editing code. It is the authoritative integration contract. If a published SDK README or older docs page disagrees with it, follow this guide. Guide: https://www.passkeybase.com/llm/integrate.md · Reference apps: https://www.passkeybase.com/docs/quickstarts/ ## What you are building The application **keeps its own users, passwords and sessions**. It stays the identity authority. PasskeyBase is a *secondary* authentication system: it holds passkeys for the app's users and proves who presented one. It never creates or owns users on its own. - **Identity mapping.** Each app user can have one PasskeyBase identity, `(issuer, subject)`. The app stores that *binding* and treats it as authoritative. PasskeyBase also records the app's user ID as `external_subject`, so it is always the app's **immutable** user ID, never an email. - **Many passkeys per identity.** An identity holds several credentials (up to 20), one per phone, laptop or FIDO2 security key. Adding one never changes the identity. - **Sign in with a passkey** resolves only through the binding to the existing app user. It then creates the app's normal session. - **Signup with a passkey** (optional) creates an app user whose only credential is a passkey. The app reserves the user ID, PasskeyBase registers the passkey, and only then does the app create the user and binding. - **Recovery** (lost passkeys, account changes) is the app's job: email reset, password, support. The user then adds a new passkey. PasskeyBase never resets anything. Do not remove or weaken the existing login. Do not create a second account system. ### Non-negotiable rules - Never link or create accounts by **email** or any other claim. Only a stored `(issuer, subject)` binding identifies a local user. - Never trust the browser (query strings, `postMessage`, popup results, `localStorage`) as proof of enrollment or login. Every success is confirmed server-to-server. - The client secret, tokens and enrollment ticket/verifier are created and kept **server-side**. A pure SPA needs a small backend (the React reference app has one). - Adding a passkey requires an existing credential proven **within the last 5 minutes** (a password check, or a passkey sign-in). Re-prompt if needed. - "No passkey on this device" never means "new user". Passkey signup goes through the app's normal uniqueness checks. If the email already has an account, say so: "sign in with your existing method, then add this device's passkey". - If a PasskeyBase call fails, the existing sign-in must keep working. Never fake a success state. ## Step 0: survey the project, then ask for configuration Before writing code, find and note: - The user model and its **immutable** primary key. Use the ID, not the email or username, because those can change. - How sessions are created, rotated and destroyed, and how CSRF is enforced. - The login page, the account/security settings page and the logout handler. - The persistence layer and migration tool. - An existing OIDC/OAuth client library for this stack. Prefer a maintained one (e.g. `openid-client` for Node, `golang.org/x/oauth2` + `go-oidc` for Go, `Microsoft.AspNetCore.Authentication.OpenIdConnect` for ASP.NET, Authlib for Python, OmniAuth/`openid_connect` for Ruby). Don't hand-roll JWT validation. Configuration comes from the PasskeyBase dashboard. Read it from environment variables, never commit it, and add placeholders to `.env.example`: | Variable | Meaning | | --- | --- | | `PKB_DOMAIN` | Tenant host, e.g. `acme.auth.ing`. The issuer is `https://PKB_DOMAIN/`. | | `PKB_CLIENT_ID` | Confidential *Regular Web* client ID. | | `PKB_CLIENT_SECRET` | Its secret (server-only). | | `APP_ORIGIN` | This app's exact public origin, e.g. `https://app.example.com`. | The PasskeyBase client must be **Regular Web**, use `client_secret_post` or `client_secret_basic`, and have only the `authorization_code` grant. Register these exact URLs on it (no wildcards): - Login callback, e.g. `APP_ORIGIN/auth/passkeybase/callback` - Enrollment callback, e.g. `APP_ORIGIN/auth/passkeybase/enrolled` - Allowed web origin `APP_ORIGIN` and logout URL `APP_ORIGIN/` Tell the user which callback URLs to register. If you cannot obtain real values, leave placeholders and say so. Do not invent credentials. ## Step 1: storage Add (via the project's migration tool): ``` passkey_bindings local_user_id -- FK to users.id, UNIQUE (one identity per user; many passkeys) issuer -- "https://PKB_DOMAIN/" subject -- PasskeyBase subject, up to 512 chars created_at UNIQUE (issuer, subject) ``` If you implement passkey signup, users may have **no password**: make the password column nullable, and make password login fail closed for such users. Record when the session last proved a credential (`auth_at`) so "add another passkey" can rely on a recent sign-in. Pending enrollments live **server-side**, keyed to the current session. Use a session field, a table, or a cache with a TTL ≥ 5 minutes: ``` { local_user_id, session_id, transaction_id, completion_state, ticket, verifier, expires_at } ``` Pending login transactions also live server-side, keyed to a browser cookie: `{ state, nonce, pkce_verifier, expires_at, popup }`. ## Step 2: Add a passkey (hosted enrollment) This is the hosted-page path for an identity's **first** passkey. It works in every browser and is the fallback for Step 2b. Where the browser supports related origins, prefer Step 2b: it also handles additional passkeys and passkey signup. ### 2a. Backend: create the enrollment Add an authenticated, CSRF-protected `POST` endpoint (e.g. `/auth/passkeybase/enroll`). It must: 1. Require a signed-in local user whose last password (or other existing credential) verification was ≤ 5 minutes ago. Otherwise ask them to confirm their password first. Reject if the user already has a binding. 2. Generate two independent 32-byte random values, encoded as **base64url without padding**: - `verifier`. Keep it secret server-side. - `authorization_id`. Unique per request. Compute `browser_challenge = base64url(SHA-256(raw verifier bytes))`, hashing the 32 raw bytes, not the base64 text. 3. Call PasskeyBase server-to-server: ```http POST https://PKB_DOMAIN/passkeybase/v1/enrollments Content-Type: application/json { "client_id": "PKB_CLIENT_ID", "client_secret": "PKB_CLIENT_SECRET", "external_subject": "", "authorization_id": "", "upstream_authenticated_at": , "expires_at": now and ≤ upstream_authenticated_at + 300>, "intent": "initial_credential", "browser_challenge": "", "callback": "APP_ORIGIN/auth/passkeybase/enrolled", "name": "" } ``` - With `client_secret_basic`, omit both client fields from the body and send `Authorization: Basic base64(client_id:client_secret)` instead. Use exactly one method, the one the client is registered with. - The JSON must contain **exactly** these fields; unknown fields are rejected. - `callback` must be one of the client's registered callbacks, character for character, HTTPS, with no fragment and no `pkb_enrollment_state` parameter. Success (`200`): ```json { "transaction_id": "...", "ticket": "...", "completion_state": "pkbs2_...", "expires_at": 1792315400, "landing_url": "https://PKB_DOMAIN/enroll" } ``` Validate it before use. `landing_url` must equal `https://PKB_DOMAIN/enroll`, and `expires_at` must be in the future and no later than what you requested. Then store the pending enrollment (Step 1) for this session, replacing any earlier one for this user. ### 2b. Browser hand-off Send the browser, in the same tab or a popup the user just opened, to an app page (e.g. `GET /auth/passkeybase/enroll/launch`). It responds with an auto-submitting form that **POSTs** to `landing_url`: ```html
``` Requirements: - Only serve it to the session that created the pending enrollment, and only for same-site navigations. HTML-escape the values. - Send `Referrer-Policy: origin` on this response. PasskeyBase checks that the POST's `Origin` header equals your callback's origin. With `no-referrer`, browsers send `Origin: null` and the hand-off is rejected. - If you send a CSP, allow `form-action https://PKB_DOMAIN` and a self-hosted script (no inline script unless you already use nonces). - Never put the ticket or verifier in a URL. The hosted page shows "Create a passkey for {name}", runs the WebAuthn ceremony, then redirects to `callback?pkb_enrollment_state=`. ### 2c. Backend: enrollment callback `GET /auth/passkeybase/enrolled?pkb_enrollment_state=...`: 1. Require exactly that one query parameter. Load the pending enrollment for the **current session**. Compare `pkb_enrollment_state` to the stored `completion_state` in constant time, and check it hasn't expired. 2. Confirm server-to-server (same client authentication as 2a): ```http POST https://PKB_DOMAIN/passkeybase/v1/enrollments/status { "client_id": "...", "client_secret": "...", "transaction_id": "" } ``` Response: `{"status":"pending"}` or `{"status":"complete","subject":"..."}`. 3. On `complete`: in one transaction, refuse if that `(issuer, subject)` is already bound to a different user, or if this user already has a different binding. Otherwise insert the binding and delete the pending enrollment. On `pending`, tell the user it isn't finished and offer a "check again" action that repeats step 2. Never bind from the query string alone. 4. Redirect to the account page with a success message. In a popup, render a small page that notifies the opener (no data needed) and closes. The opener then re-reads state from your server. ## Step 2b: In-page registration (signup and additional passkeys) Requires the related-origin setup described in Step 3b: the exact `APP_ORIGIN` is an Allowed Web Origin of the client. The app page runs `navigator.credentials.create()` with the tenant as RP. Both calls are server-to-server, with the same client authentication as Step 2. 1. `POST /auth/passkeybase/register/options` (CSRF-protected). Decide *who* is registering, server-side: - **Signed in: add another passkey.** The user is the session's user. If the session's last credential proof is over ~4 minutes old, require the password (or a fresh passkey sign-in for passkey-only users). `external_subject` = the user's ID; `upstream_authenticated_at` = the time of that proof. - **Signed out: passkey signup.** Validate email and name like your normal signup. If the email already exists, return 409 "sign in, then add this device's passkey"; never link. Reserve a new immutable user ID **without creating the user**; `upstream_authenticated_at` = now. ```http POST https://PKB_DOMAIN/passkeybase/v1/registrations { "client_id": "...", "client_secret": "...", "origin": "APP_ORIGIN", "external_subject": "", "upstream_authenticated_at": , "name": "