Passkeys

Passwords and one-time codes can be typed into a convincing fake login page. Passkeys cannot: they are WebAuthn credentials, a key pair kept on a device or synced by a platform account, and the browser only uses them on your own site. They also verify the person on the device (with biometrics or a PIN), so one passkey is both factors at once.

In Better IAM a passkey can sign a person in on its own, and satisfies MFA when it does, or it can answer the second step of a password or passwordless sign-in. Use passkeys when you want phishing-resistant sign-in, or as a faster second factor than an authenticator code.

Setup

import { betterIam } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';

export const iam = betterIam({
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: 'https://app.example.com',
  trustedOrigins: ['https://admin.example.com'],
  authentication: {
    passkeys: { rpID: 'example.com', rpName: 'Acme Cloud' },
  },
});

npx better-iam migrate --config better-iam.config.mjs

import { createIamClient } from 'better-iam/client';
import type { iam } from './iam';

export const client = createIamClient<typeof iam>();

Usage

Register a passkey

People add passkeys from their account page, while signed in with a recently authenticated session. Recent authentication stops someone who finds an unlocked laptop from adding their own passkey to the account.

import { client } from './lib/iam-client';

const { challengeId, options } = await client.auth.beginPasskeyRegistration();

import { startRegistration } from 'better-iam/client/passkeys';

const response = await startRegistration({ optionsJSON: options });

const { id, name } = await client.auth.finishPasskeyRegistration({
  challengeId,
  response,
  name: 'Work laptop', // optional, at most 64 characters
});

The server verifies the challenge, origin, RP ID, and user verification, then stores the public key. Without a name, the passkey is labeled from what the authenticator reports about itself: "This device" for a built-in authenticator, "Phone" for a cross-device (hybrid) one, "Security key" for USB, NFC, or Bluetooth keys, and "Passkey" otherwise. Registration is audited as auth:passkey:create with the name.

A credential is unique for the relying party across the whole installation, including across tenant accounts: registering the same credential twice fails with PASSKEY_EXISTS.

Sign in with a passkey

Signing in with a passkey takes two calls around the browser ceremony. auth.beginPasskeyAuthentication issues a challenge and the options for the browser, and auth.finishPasskeyAuthentication verifies the signed response and issues a session that has already passed MFA (method: 'passkey'). Through the HTTP handler the session is set as the session cookie (__Host-better-iam.session on HTTPS, better-iam.session on loopback HTTP).

// <input name="email" autoComplete="username webauthn" /> on the login form enables autofill.
import { browserSupportsWebAuthnAutofill, startAuthentication } from 'better-iam/client/passkeys';
import { client } from './lib/iam-client';

if (await browserSupportsWebAuthnAutofill()) {
  const { challengeId, options } = await client.auth.beginPasskeyAuthentication({ tenantId });
  const response = await startAuthentication({ optionsJSON: options, useBrowserAutofill: true });
  await client.auth.finishPasskeyAuthentication({ tenantId, challengeId, response });
}

Routes: POST /api/iam/auth/beginPasskeyAuthentication, POST /api/iam/auth/finishPasskeyAuthentication

• The sign-in challenge is valid for five minutes. An autofill request can wait longer than that, so start a fresh one before it expires (the console refreshes after four minutes).
• Discovery names nobody, so it is rate limited per client address, with ten times the ordinary allowance, because login pages start one on every visit.
• A discovered passkey that is not registered in this organization, a user handle that does not match the account, or a failed verification is refused with INVALID_PASSKEY.
• The server checks the challenge, origin, RP ID, user verification, the signature, and the signature counter, and records the passkey's lastUsedAt.

Use a passkey as a second factor

People who still sign in with a password can use their passkey as the second step, which is faster than typing a code and cannot be phished. When a password or passwordless sign-in returns mfaRequired with passkeyAvailable: true (the person has at least one passkey), auth.beginPasskeyMfa issues WebAuthn options bound to that sign-in challenge, and auth.finishPasskeyMfa verifies the response and issues the session:

import { startAuthentication } from 'better-iam/client/passkeys';
import { client } from './lib/iam-client';

const { challengeId, options } = await client.auth.beginPasskeyMfa({ tenantId, challenge: result.challenge });
const response = await startAuthentication({ optionsJSON: options });
const session = await client.auth.finishPasskeyMfa({
  tenantId,
  challengeId,
  response,
  rememberDevice: true, // optional; see "remember this device"
});

Routes: POST /api/iam/auth/beginPasskeyMfa, POST /api/iam/auth/finishPasskeyMfa

The assertion is verified like a passkey sign-in (challenge, origin, RP ID, user verification, signature, counter) and bound to the pending sign-in challenge, which must still be open and belong to the same person (INVALID_CHALLENGE otherwise). Both challenges are consumed together. The session keeps the method of the first factor, such as password. Without a registered passkey, beginPasskeyMfa fails with FEATURE_DISABLED. With rememberDevice: true, the response can carry a deviceToken; see remember this device.

List, rename, and delete passkeys

People collect passkeys on several devices over time, and need to recognize and remove old ones, such as the passkey on a phone they sold. Three calls back an account page:

• auth.listPasskeys returns the caller's passkeys, newest first, without key material (fields below).
• auth.renamePasskey gives a passkey a label the person recognizes, such as "YubiKey 5C". Audited as auth:passkey:rename.
• auth.deletePasskey removes one. It needs recent authentication, ends every session of the person, and is audited as auth:passkey:delete.

import { client } from './lib/iam-client';

const passkeys = await client.auth.listPasskeys();
await client.auth.renamePasskey({ id: passkeys[0].id, name: 'YubiKey 5C' });
await client.auth.deletePasskey({ id: passkeys[1].id });

Routes: POST /api/iam/auth/listPasskeys, POST /api/iam/auth/renamePasskey, POST /api/iam/auth/deletePasskey

Each listed passkey carries:

Removing the last passkey is refused with LAST_AUTHENTICATOR unless the person has another way to sign in: a password, or a verified email or phone number with passwordless sign-in enabled. That keeps people from locking themselves out. A passkey ID that is not the caller's fails with NOT_FOUND.

auth.mfaStatus() reports how many passkeys a person has, and tenants.usage counts people with an authenticator or a passkey as MFA-enrolled.

Require passkeys

To make an organization phishing-resistant, set its policy's allowedMethods to ['passkey']. Password, passwordless, and federated sign-in are then refused with METHOD_NOT_ALLOWED before any credential is examined. Policies can also demand a passkey session for one action only, with a condition on principal.authMethod:

{
  effect: 'allow',
  actions: ['billing:refund'],
  resources: ['invoice/*'],
  conditions: { StringEquals: { 'principal.authMethod': 'passkey' } },
}

Options

Schema

Passkeys and their ceremonies are stored in two collections of the document store:

See Database schema for every collection.

Errors

Next steps