Allow passkey reuse across your sites with Related Origin Requests  |  Articles  |  web.dev (2024)

Passkeys are tied to a specific website and can only be used for signing in on the website they were created for.

This is specified in the relying partyID (RP ID), which for passkeys created for the example.com domain could be www.example.com or example.com.

While RP IDs prevent passkeys from being used as a single credential forauthenticating everywhere, they create issues for:

• Sites with multiple domains: Users can't use the same passkey tosign in across different country-specific domains (for exampleexample.com, and example.co.uk) managed by the same company.
• Branded domains: Users can't use the same credential acrossdifferent domains used by a single brand (for example acme.com andacmerewards.com).
• Mobile apps: Mobile apps often don't have their own domain, makingcredential management challenging.

There are workarounds based on identity federation, and others based oniframes, but they are inconvenient in some cases. Related Origin Requests offera solution.

Solution

WithRelated Origin Requests,a website can specify origins allowed to use its RP ID.

This unlocks the possibility for users to reuse the same passkey across multiple sites you operate.

To use Related Origin Requests, you need to serve a special JSON file at aspecific URL https://{RP ID}/.well-known/webauthn. If example.com wants toallow the additional origins to use it as an RP ID, it should serve the followingfile at https://example.com/.well-known/webauthn:

{ "origins": [ "https://example.co.uk", "https://example.de", "https://example-rewards.com" ]}

Next time any of these sites makes a call for passkey creation(navigator.credentials.create) or authentication (navigator.credentials.get)that uses example.com as an RP ID, the browser will notice an RP ID thatmismatches the requesting origin. If the browser supports Related OriginRequests, it first looks for awebauthn file at https://{RP ID}/.well-known/webauthn. If the file exists,the browser checks whether the origin making the request is allowlisted in thatfile. If so, it proceeds to passkey creation or authentication steps.If the browser doesn't support Related Origin Requests, it throws a SecurityError.

Browser support

• Chrome: Supported starting from Chrome128.
• Safari: Supported starting from macOS 15 beta 3, and on mobile iOS 18 beta 3.
• Firefox:Awaiting position.

The following demo uses the example of two sites, https://ror-1.glitch.me and https://ror-2.glitch.me.
To enable users to sign in with the same passkey across both of those sites, it uses Related Origin Requests to allow ror-2.glitch.me to use ror-1.glitch.me as its RP ID.

Demo

https://ror-2.glitch.me implements Related Origin Requests to use ror-1.glitch.me as an RP ID, so both ror-1 and ror-2 use ror-1.glitch.me as an RP ID upon creating a passkey or authenticating with it.
We've also implemented a shared passkey database across these sites.

Observe the following user experience:

• You can successfully create a passkey, and authenticate with it, on ror-2—even though its RP ID is ror-1 (and not ror-2).
• Once you create a passkey on either ror-1 or ror-2, you can authenticate with it on both ror-1 and ror-2. Because ror-2 specifies ror-1 as an RP ID, making a passkey creation or authentication request from any of these sites is the same as making the request on ror-1. The RP ID is the only thing that ties a request to an origin.
• Once you create a passkey on either ror-1 or ror-2, it can be autofilled by Chrome on both ror-1 and ror-2.
• A credential created on any of these sites will have an RP ID of ror-1.

See code:

• See the ./well-known/webauthn file set up in the ror-1 codebase.
• See RP_ID_ROR occurrences in the ror-2 codebase.

If you want your users to be able to sign in with the same passkey acrosssite-1 and site-2, implement an account database that is shared across thesetwo sites.

Step 2: Set up your .well-known/webauthn JSON file in site-1

First, configure site-1.com such that it allows site-2.com to use it as anRP ID. To do so, create your webauthn JSON file:

{ "origins": [ "https://site-2.com" ]}

The JSON object must contain key named origins whose value is an array of oneor more strings containing web origins.

Important limitation: Maximum 5 labels

Each element of this list will be processed to extract the eTLD + 1 label.For example, the eTLD + 1 labels of example.co.uk and example.de are bothexample. But the eTLD + 1 label of example-rewards.com is example-rewards.In Chrome, the maximum number of labels is 5.

Step 3: Serve your .well-known/webauthn JSON in site-1

Then, serve your JSON file under site-1.com/.well-known/webauthn.

For example, in express:

app.get("/.well-known/webauthn", (req, res) => { const origins = { origins: ["https://site-2.com"], }; return res.json(origins);});

Here, we're using express res.json, which already sets thecorrect content-type ('application/json');

Step 4: Specify the desired RP ID in site-2

In your site-2 codebase, set site-1.comas the RP ID everywhere needed:

• Upon credential creation:
  • Set site-1.com as the RP ID in the credential creationoptions that are passed to the navigator.credentials.createfrontend call, and typically generated server-side.
  • Set site-1.comas the expected RP ID, as you run credentialverifications before saving it to your database.
• Upon authentication:
  • Set site-1.com as the RP ID in the authentication optionsthat are passed to the navigator.credentials.get frontend call, andtypically generated server-side.
  • Set site-1.comas the expected RP ID to be verified on theserver, as you run credential verifications before authenticating the user.

Troubleshooting

Other considerations

Related Origin Requests allow your users to reuse a passkey across multiplesites.To allow your users to reuse a passkey across a website and a mobile app,use the following techniques:

• In Chrome: Digital AssetLinks. Learn more atAdd support for Digital Asset Links.
• In Safari:Associated domains.

Related Origin Requests allow your users to reuse a passkey across sites.Solutions for sharing passwords across sites vary between password managers.For Google Password Manager, use Digital Asset Links .Safari has a different system.

Role of credential managers and user agents

This goes beyond your scope as a site developer, but note that in the longerterm, the RP ID shouldn't be a user-visible concept in the user agent or thecredential manager your users are using. Instead, user agents and credentialmanagers should show users where their credentials have been used. This changewill take time to implement. A temporary solution would be to display both thecurrent website and the original registration site.