Migrating passkeys to a new domain

TL;DR

Although passkeys are bound to specific domains, it is possible to accept passkeys from other domains. This is only allowed if the source domain marks the other domain as trusted. You’ll need to update your Passlock settings and host a JSON file on the source domain.

Passkeys are resistant to phishing attacks because they’re bound to a specific domain (rpID). This does, however, raise some serious issues:

1. Domain migration - at some point you may need to change your domain. If a passkey is registered to oldsite.com, how will your users sign in on newsite.com?

2. Related domains - users may legitimately want to log in using a passkey from a different domain e.g. using an acme.com passkey on acme.co.uk.

Fortunately the specifications now support related origin requests, allowing you to accept passkeys registered to other domains.

This is not federation

Related origin requests simply allow the browser/device to present a passkey, bypassing the same site restrictions. The public key component of a passkey must reside in your vault. In practice this means you’ll use related origin requests when changing domains, not as a substitute for OpenID Connect, SAML etc.

Related Origin Requests

For the examples we’ll use two domains: oldsite.com and newsite.com. Assume existing passkeys are registered to oldsite.com, but want to use newsite.com. You have a couple of options:

Related origin request basics

The browser will only allow a related origin request if it can fetch https://oldsite.com/.well-known/webauthn over HTTPS, receive a 200 response with application/json, and the JSON body includes the calling origin (for example, https://newsite.com) in its origins array.

Use the existing Relying Party ID

The simplest option is to continue using an rpID of oldsite.com on newsite.com.

1. Setup your tenancy

Navigate to the passkey settings for your tenancy in the Passlock console.
Enter your old domain as the Relying Party ID.

Continue to use an rpID of oldsite.com

2. Whitelist the new domain

Host a /.well-known/webauthn file at the root of oldsite.com (the rpID domain), whitelisting newsite.com:

https://oldsite.com/.well-known/webauthn

{
  "origins": [
    "https://oldsite.com",
    "https://newsite.com"
  ]
}

The trade-offs

This is the simplest approach, for both users and developers. There are some drawbacks:

1. You need to host the webauthn file at oldsite.com indefinitely.

2. Some browsers/devices ignore the Relying Party name and display the rpID to users, so they will see the message “do you want to sign in with your oldsite.com passkey?” or similar.

Migrate to a new rpID

Alternatively, you can use newsite.com for new passkeys, whilst continuing to accept passkeys registered to oldsite.com.

1. Update your tenancy settings

rpID is now newsite.com, with oldsite.com as a related origin

2. Whitelist the new domain

Host a /.well-known/webauthn file at the root of oldsite.com (the rpID domain), whitelisting newsite.com:

https://oldsite.com/.well-known/webauthn

{
  "origins": [
    "https://oldsite.com",
    "https://newsite.com"
  ]
}

3. Accept legacy passkeys

By default, the browser/device will present passkeys with an rpID of newsite.com.

If you need to authenticate oldsite.com passkeys after switching your tenancy rpID to newsite.com, override the rpID on that request:

import { authenticatePasskey } from "@passlock/browser"

const result = await authenticatePasskey({
  rpId: "oldsite.com",
}, { tenancyId: "your-tenancy-id" })

This tells Passlock to fetch authentication options for oldsite.com, allowing the browser to present passkeys that were originally created for that rpID.

Note

You need to know ahead of time which domain the user’s passkey is registered to. There is currently no way to ask the device to present a passkey from oldsite.com or newsite.com.

In practice this means you’ll need to adopt a two-step login flow. Alternatively you can offer a “Sign in with your oldsite.com passkey” type button.

Caution

If you implement a custom dual-rpID fallback flow, be careful. Once a request is made for an rpID with no matching local credential, browsers can enter the roaming authenticator flow, which usually adds friction.

The trade-offs

This approach allows you to support passkeys registered to an old domain, while also registering passkeys against the new domain.

After a user has authenticated with a “legacy” passkey, you can prompt them to register a new one, using the current domain/rpID. You can even delete the old passkey for them. The downsides are:

1. You need to host the webauthn file at oldsite.com until all users have been migrated.

2. You still need to decide whether to request a passkey for the old or new rpID. There is currently no single request that asks the browser for passkeys from both domains at once.