How to migrate passkeys from one domain (rpID) to a different domain

TL;DR

While passkeys are bound to specific domains (Relying Party ID / rpId), it is possible to accept passkeys from other domains. This is only allowed if the source domain (rpId) 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 old-domain.com, how will your users sign in on new-domain.com?

2. Related domains - You may operate several domains within a group and want to allow users to share their passkey across those domains.

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

This is not federation

Related origin requests do not bypass phishing protection. They allow an origin to use a different rpId only when that rpId explicitly authorises it. To verify the passkey you will still need the public-key component in your vault.

Related Origin Requests

Assume existing passkeys are registered to old-domain.com, but want to use new-domain.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://old-domain.com/.well-known/webauthn over HTTPS, receive a 200 response with application/json, and the JSON body includes the calling origin (for example, https://new-domain.com) in its origins array.

Use the existing Relying Party ID

The simplest option is to continue using an rpId of old-domain.com, even on new-domain.com:

1. Setup your tenancy

Continue to use an rpId of old-domain.com

2. Whitelist the new domain

Host a /.well-known/webauthn file at the root of old-domain.com (the rpId domain), whitelisting new-domain.com:

https://old-domain.com/.well-known/webauthn

{
  "origins": [
    "https://old-domain.com",
    "https://new-domain.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 old-domain.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 old-domain.com passkey?” or similar.

Migrate to a new rpId

Alternatively, you can use new-domain.com for new passkeys, while continuing to accept passkeys registered to old-domain.com.

1. Update your tenancy settings

rpId is now new-domain.com, with old-domain.com as a related origin

2. Whitelist the new domain

Host a /.well-known/webauthn file at the root of old-domain.com (the rpId domain), whitelisting new-domain.com:

https://old-domain.com/.well-known/webauthn

{
  "origins": [
    "https://old-domain.com",
    "https://new-domain.com"
  ]
}

3. Accept legacy passkeys

By default, the browser/client will present passkeys with an rpId of new-domain.com.

Caution

At the time of writing, the @passlock/client helper does not expose a per-request rpId override.

If you need to authenticate old-domain.com passkeys after switching your tenancy rpId to new-domain.com, you currently need to either:

1. Keep old-domain.com as the tenancy rpId until migration is complete, or
2. Implement a custom WebAuthn flow (instead of authenticatePasskey) so you can explicitly request options for the legacy rpId.

Note

Related origin requests apply to both registration and authentication. If you use old-domain.com as the rpId for authentication, the associated registrations must also have been created with that rpId.

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 old-domain.com until all users have been migrated.

2. You need to somehow establish whether to request a passkey registered to the old or new rpId. There is currently no means of requesting a passkey from either domain.