Related Origin Requests

The Related Origin Requests (ROR) feature allows an RP to enable a passkey to be created and used across a limited set of related origins.

Use Cases  

The two use cases for Related Origin Requests (ROR) are deployments which use different country code top-level domains (ccTLD) across the world, and deployments where different branding is used for different services.

To address these use cases, it is recommended to leverage industry-standard federation protocols such as OpenID Connect. This approach facilitates a centralized login experience, by using a dedicated login page (e.g., login.example.com) that serves as the authentication point for all origins and services.

ROR is designed to be used when federation is not possible.

  Note

ROR is a WebAuthn feature for the web. App platforms have existing mechanisms for mapping native apps to one or more web origins: Digital Asset Links for Android and Associated Domains on Apple platforms.

Country Code Top Level Domains (ccTLDs)  

Many global organizations utilize country code top level domains (ccTLDs) to cater to their international services. For instance, a shopping website might use shopping.com for users in the United States, while also having shopping.ca for Canada, shopping.co.uk for the United Kingdom, shopping.ie for Ireland, and shopping.sg for Singapore, among others. However, a passkey created on shopping.com can’t be used on shopping.sg, and vice versa.

Alternate Branding  

Some organizations offer additional services with different or extended branding and share the same accounts. For instance, a shopping site might have their own credit card or their own travel services, which are accessed via different websites.

How It Works  

Related Origin Requests (ROR) works by allowing a Relying Party (RP) to provide a list of valid origins for a given Relying Party ID (RP ID).

During a WebAuthn ceremony, if the RP ID and origin do not match, the WebAuthn client can query the RP for a list of valid origins. The client processes that origin list and then re-evaluates the binding based on this additional context. If an origin is matched, the client will continue with the request in the context of the RP ID.

A label, in the context of this feature, is the name directly preceding the effective top level domain. For instance, shopping is the label for https://shopping.com, https://shopping.co.uk, https://shopping.co.jp, https://shopping.net, and https://shopping.org. Labels are used as a way to support the large number of entries required to support ccTLDs, while enabling clients to restrict the number of unique origins to prevent abuse.

If there are 30 origins in the list, all with the same label, these count as 1 unique label. WebAuthn requires client implementations to support at least 5 unique labels, however there are no known clients which support more than 5, so that should be treated as the maximum for deployments.

Below are three examples of origin lists and their respective label counts.

{
  "origins": [
    "https://shopping.com",
    "https://shopping.co.uk",
    "https://shopping.co.jp",
    "https://shopping.ie",
    "https://shopping.ca",
    "https://shopping.net",
    "https://shopping.org",
    "https://shopping.github.io"
  ]
}

{
  "origins": [
    "https://shopping.com",
    "https://shopping.co.uk",
    "https://shopping.co.jp",
    "https://shopping.ie",
    "https://shopping.ca",
    "https://myshoppingrewards.com",
    "https://myshoppingrewards.co.uk",
    "https://myshoppingrewards.co.jp",
    "https://myshoppingrewards.ie",
    "https://myshoppingrewards.ca",
    "https://myshoppingtravel.com",
    "https://myshoppingtravel.co.uk",
    "https://myshoppingtravel.co.jp",
    "https://myshoppingtravel.ie",
    "https://myshoppingtravel.ca"
  ]
}

{
  "origins": [
    "https://shopping.com",
    "https://shopping.co.uk",
    "https://shopping.co.jp",
    "https://shopping.ie",
    "https://shopping.ca",
    "https://myshoppingcard.us",
    "https://myshoppingrewards.com",
    "https://myshoppingrewards.co.uk",
    "https://myshoppingrewards.co.jp",
    "https://myshoppingrewards.ie",
    "https://myshoppingrewards.ca",
    "https://myshoppingcreditcard.co.uk",
    "https://myshoppingcreditcard.co.jp",
    "https://myshoppingcreditcard.ie",
    "https://myshoppingcreditcard.ca",
    "https://myshoppingtravel.com",
    "https://myshoppingtravel.co.uk",
    "https://myshoppingtravel.co.jp",
    "https://myshoppingtravel.ie",
    "https://myshoppingtravel.ca"
  ]
}

Requirements  

Client Support  

The Device Support matrix lists the browsers which support Related Origin Requests. The Passkeys Feature Detect page will also attempt to detect ROR support in the browser in which the page was loaded.

To dynamically detect support for Related Origin Requests on an enrollment or login page, Relying Parties should check for relatedOrigins in the WebAuthn Get Client Capabilities (PublicKeyCredential.getClientCapabilities()) response.

If Related Origin Requests is not supported by the client, fallback logic can be used. See Existing Deployments below.

Relying Party Changes  

A JSON document must be hosted at the WebAuthn well-known path for the Relying Party ID, /.well-known/webauthn.

For example, if the RP ID is shopping.com, the full URL would be https://shopping.com/.well-known/webauthn.

The server must respond with a content type of application/json.

The JSON document must have a member named origins, containing an array of valid origins for use with passkeys scoped for the RP ID.

See Deployment Considerations below for details on choosing an RP ID.

Below is an example for the RP ID shopping.com.

{
  "origins": [
    "https://shopping.com",
    "https://myshoppingrewards.com",
    "https://myshoppingcreditcard.com",
    "https://myshoppingtravel.com",
    "https://shopping.co.uk",
    "https://shopping.co.jp",
    "https://shopping.ie",
    "https://shopping.ca"
  ]
}

Deployment Considerations  

Greenfield Deployments  

The most important design decision for a greenfield deployment using ROR is picking a common Relying Party ID (RP ID) to be used for passkeys across all origins. All WebAuthn requests across all related origins will use that as rp.id.

It is recommended to pick the most commonly used and/or understood domain for the common RP ID. This is typically the domain closely associated with the organization’s brand, and is often the .com.

Existing Deployments  

For deployments where passkeys are already rolled out with multiple RP IDs or in cases where Related Origin Requests is not supported by the browser, there are some unique considerations and requirements.

Considerations  

• Users with a passkey for the “local” RP ID / origin will be able to use all passkeys experiences as normal.
• Users with a passkey for another RP ID / related origin, will require an identifier first flow and a backend lookup.

Requirements  

• Each existing RP ID will need to host the WebAuthn well-known document, with all of the other origins listed in it. This will allow reciprocal use of passkeys
• The account database will need to know which RP ID was used for each passkey (this could be an explicit property or inferred based on other data)
• The username field on the login page will need to support fallback to an identifier first flow with backend lookup

Flow  

This flow assumes the autofill UI for passkeys is being used.

1. Make a conditional WebAuthn request normally on page load
2. If the promise resolves, process the WebAuthn response as normal and sign the user in
3. If the the user enters a username and continues:
   • abort the conditional WebAuthn request
   • send a request to your backend to retrieve the RP ID for the username
4. Redirect the user to the origin matching the RP ID (typically using a federation protocol)
5. Fetch fresh WebAuthn parameters from the backend
6. Call WebAuthn with the fresh parameters and the correct RP ID
7. Redirect the user back to the original origin with the necessary artifacts (typically a federated assertion or token)

Example  

In this example, passkeys have previously been rolled out to the following users:

• https://shopping.com users, with an RP ID of shopping.com
• https://shopping.co.uk users, with an RP ID of shopping.co.uk

A user with a passkey for shopping.com navigates to https://shopping.com, clicks into the username field, selects their passkey, performs user verification, and is then signed in!

A user with a passkey for shopping.co.uk has traveled to the US and navigates to https://shopping.co.uk. Based on location data, the user is redirected to https://shopping.com. They click into the username field and do not see any passkey available. They then type their username and click continue. A backend lookup occurs, the user is redirected to https://shopping.co.uk, WebAuthn is now invoked with an RP ID of shopping.co.uk, the user selects their passkey, performs user verification, and is redirected back to https://shopping.com!

Additional Information