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 by hosting a .well-known/webautn file.

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

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

2. Related domains - users may legitimately want to present a passkey from a different domain e.g. presenting an example.com passkey to example.co.uk.

Fortunately the passkey specs now support Related Origin Requests, allowing you to accept passkeys bound 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 still reside in your vault. In practice this means you’ll use related origin requests for domains you control.

Related Origin Requests

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 and the response is a JSON document listing the calling origin (for example, https://newsite.com) in its origins array.

For the examples we’ll use two domains: oldsite.com and newsite.com.

Assume existing passkeys are registered to oldsite.com, and you want to migrate your domain to newsite.com. You have a couple of options:

Continue using the existing Relying Party ID on the new domain

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

1. Authorize passkey ceremonies with the old RP ID

When your backend authorizes registration or authentication, keep passing oldsite.com as the RP ID:

backend/register.ts

const result = await passlock.authorizePasskeyRegistration({
  rpId: "oldsite.com",
});

backend/authenticate.ts

const result = await passlock.authorizePasskeyAuthentication({
  rpId: "oldsite.com",
});

2. Whitelist the new domain

Host a /.well-known/webauthn file at the root of oldsite.com (the RP ID 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 users and developers. However, there are some drawbacks:

1. You need to host https://oldsite.com/.well-known/webauthn indefinitely.

2. Some browsers/devices ignore the Relying Party Name and display the RP ID 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 RP ID

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

1. Register new passkeys with the new RP ID

For new or replacement passkeys, register them with newsite.com instead of oldsite.com.

backend/registration.ts

const result = await passlock.authorizePasskeyRegistration({
  rpId: "newsite.com",
});

2. Whitelist the new domain

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

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

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

3. Accept legacy passkeys

By default, you should authenticate passkeys with the new newsite.com RP ID. Newly created passkeys will work fine.

backend/authentication.ts

const result = await passlock.authorizePasskeyAuthentication({
  rpId: "newsite.com",
})

To authenticate legacy oldsite.com passkeys you will need to pass oldsite.com as the RP ID:

backend/authentication.ts

const result = await passlock.authorizePasskeyAuthentication({
  rpId: "oldsite.com",
})

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

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, where the user first presents their account identifier. You will then know which domain the passkey is registered to, and can then prompt to authenticate with the appropriate RP ID.

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 RP ID with no matching local credential, browsers can enter the roaming authenticator flow, which usually adds friction.

4. Migrate legacy passkeys

It’s a good idea to prompt legacy users to create a new passkey, which will be registered against the new RP ID. The best time to do this is usually following a successful login with a legacy passkey:

backend/register.ts

const result = await passlock.authorizePasskeyRegistration({
  rpId: "newsite.com",
})

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/RP ID. You can even delete the old passkey for them. The downsides are:

1. You need to host https://oldsite.com/.well-known/webauthn until all users have been migrated.

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