adds Related Origin Requests

index.bs

@@ -1228,6 +1228,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 : <dfn>Non-Discoverable Credential</dfn>
 :: This is a [=credential=] whose [=credential ID=] must be provided in {{PublicKeyCredentialRequestOptions/allowCredentials}} when calling {{CredentialsContainer/get()|navigator.credentials.get()}} because it is not [=client-side discoverable credential|client-side discoverable=]. See also [=server-side credentials=].
 
+: <dfn>Origin Label</dfn>
+:: The portion of a domain name preceding the effective top-level domain, as defined in the Public Suffix List [[PSL]]. This is often referred to as the eTLD+1. For example, the origin label for example.co.uk and example.de is `example`.
+
 : <dfn>Public Key Credential</dfn>
 :: Generically, a *credential* is data one entity presents to another in order to *authenticate* the former to the latter
     [[RFC4949]]. The term [=public key credential=] refers to one of: a [=public key credential source=], the
@@ -1824,11 +1827,37 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
 
                 :   is present
                 ::  If <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> [=is not a
-                    registrable domain suffix of and is not equal to=] |effectiveDomain|, throw a "{{SecurityError}}" {{DOMException}}.
+                    registrable domain suffix of and is not equal to=] |effectiveDomain|, and if the client
+
+                    <dl class="switch">
+                        :   supports [[#sctn-related-origins|related origin requests]]
+                        ::  1. Let |rpIdRequested| be the value of <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code>.
+
+                            1. Let |maxLabels| be the number of maximum [=origin labels=] allowed by client policy.
+
+                            1. Fetch the well-known URL for the RP ID (<code>https://|rpIdRequested|/.well-known/webauthn</code>).
+
+                                1. If the fetch fails, the response does not have a content type of `application/json`, or does not have a status code (after following redirects) of 200, then throw a "{{SecurityError}}" {{DOMException}}.
+                                1. If the body of the resource is not a valid JSON object, then throw a "{{SecurityError}}" {{DOMException}}.
+                                1. If the value of the |origins| property of the JSON object is missing, or is not an array of strings, then throw a "{{SecurityError}}" {{DOMException}}.
+
+                            1. Let |originLabelsSeen| be an empty set.
+                            1. [=set/For each=] string in |origins|:
+                                1. Let |url| be the result of parsing the string as a URL. If that fails, continue with the next element in the list.
+                                1. Let |domain| be the [=effective domain=] of |url|. If that is null, continue with the next element of the list.
+                                1. Remove any [=public suffix=] from the end of |domain|, including private registries and unknown registries. If |domain| is now empty, continue with the next element of the list.
+                                1. Split |domain| into [=origin labels|labels=] and let |label| be the right-most one.
+                                1. If |label| is not in |labelsSeen| and:
+                                    1. If the number of elements in |labelsSeen| is less than |maxLabels|, then insert |label| into |labelsSeen|.
+                                    1. Otherwise, continue with the next element of the list.
+                                1. If |rpIdRequested| and |url| are [=same origin=], then [=continue=].
+
+                        :   does not support [[#sctn-related-origins|related origin requests]]
+                        ::  throw a "{{SecurityError}}" {{DOMException}}.
+                    </dl>
 
-                :   Is not present
-                ::  Set <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> to
-                    |effectiveDomain|.
+                :   is not present
+                ::  Set <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> to |effectiveDomain|.
             </dl>
 
         Note: <code>|pkOptions|.{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> represents the
@@ -2314,19 +2343,47 @@ When this method is invoked, the user agent MUST execute the following algorithm
         PKI-based security.
 
         <li id='GetAssn-DetermineRpId'>
-            If <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> is not present, then set |rpId| to
-                |effectiveDomain|.
+            If <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code>
+                <dl class="switch">
 
-                Otherwise:
+                    :   is present
+                    ::  If <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> [=is not a
+                        registrable domain suffix of and is not equal to=] |effectiveDomain|, and if the client
 
-                1. If <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> [=is not a registrable domain suffix of and is not
-                    equal to=] |effectiveDomain|, throw a "{{SecurityError}}" {{DOMException}}.
+                        <dl class="switch">
+                            :   supports [[#sctn-related-origins|related origin requests]]
+                            ::  1. Let |rpIdRequested| be the value of <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code>
+
+                                1. Let |maxLabels| be the number of maximum [=origin labels=] allowed by client policy.
+
+                                1. Fetch the well-known URL for the RP ID (<code>https://|rpIdRequested|/.well-known/webauthn</code>).
+
+                                    1. If the fetch fails, the response does not have a content type of `application/json`, or does not have a status code (after following redirects) of 200, then throw a "{{SecurityError}}" {{DOMException}}.
+                                    1. If the body of the resource is not a valid JSON object, then throw a "{{SecurityError}}" {{DOMException}}.
+                                    1. If the value of the |origins| property of the JSON object is missing, or is not an array of strings, then throw a "{{SecurityError}}" {{DOMException}}.
+
+                                1. Let |originLabelsSeen| be an empty set.
+                                1. [=set/For each=] string in |origins|:
+                                    1. Let |url| be the result of parsing the string as a URL. If that fails, continue with the next element in the list.
+                                    1. Let |domain| be the [=effective domain=] of |url|. If that is null, continue with the next element of the list.
+                                    1. Remove any [=public suffix=] from the end of |domain|, including private registries and unknown registries. If |domain| is now empty, continue with the next element of the list.
+                                    1. Split |domain| into [=origin labels|labels=] and let |label| be the right-most one.
+                                    1. If |label| is not in |labelsSeen| and:
+                                        1. If the number of elements in |labelsSeen| is less than |maxLabels|, then insert |label| into |labelsSeen|.
+                                        1. Otherwise, continue with the next element of the list.
+                                    1. If |rpIdRequested| and |url| are [=same origin=], then [=continue=].
+
+                            :   does not support [[#sctn-related-origins|related origin requests]]
+                            ::  throw a "{{SecurityError}}" {{DOMException}}.
+                        </dl>
 
-                1. Set |rpId| to <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code>.
+                    :   is not present
+                    ::  Set <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> to |effectiveDomain|.
+                </dl>
 
-                    Note: |rpId| represents the caller's [=RP ID=]. The [=RP ID=] defaults to being the caller's [=environment
-                    settings object/origin=]'s [=effective domain=] unless the caller has explicitly set
-                    <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> when calling {{CredentialsContainer/get()}}.
+            Note: |rpId| represents the caller's [=RP ID=]. The [=RP ID=] defaults to being the caller's [=environment
+            settings object/origin=]'s [=effective domain=] unless the caller has explicitly set
+            <code>|pkOptions|.{{PublicKeyCredentialRequestOptions/rpId}}</code> when calling {{CredentialsContainer/get()}}.
         </li>
 
 1. Let |clientExtensions| be a new [=map=] and let |authenticatorExtensions| be a new [=map=].
@@ -3963,6 +4020,7 @@ Note: The {{UserVerificationRequirement}} enumeration is deliberately not refere
         "hybridTransport",
         "passkeyPlatformAuthenticator",
         "userVerifyingPlatformAuthenticator",
+        "relatedOriginRequests"
     };
 </xmp>
 
@@ -3985,6 +4043,9 @@ Note: The {{ClientCapability}} enumeration is deliberately not referenced, see [
 
     :   <dfn>userVerifyingPlatformAuthenticator</dfn>
     ::  The [=WebAuthn Client=] supports usage of a [=user-verifying platform authenticator=].
+
+    :   <dfn>relatedOriginRequests</dfn>
+    ::  The [=WebAuthn Client=] supports [[#sctn-related-origins|Related Origin Requests]].
 </div>
 
 ### User-agent Hints Enumeration (enum <dfn enum>PublicKeyCredentialHints</dfn>) ### {#enum-hints}
@@ -4046,7 +4107,38 @@ To override this default policy and indicate that a cross-origin <{iframe}> is a
 
 [=[RPS]=] utilizing the WebAuthn API in an embedded context should review [[#sctn-seccons-visibility]] regarding [=UI redressing=] and its possible mitigations.
 
+## Using Web Authentication across related origins ## {#sctn-related-origins}
+
+By default, Web Authentication requires that the [=RP ID=] be equal to the [=determines the set of origins on which the public key credential may be exercised|origin=]'s [=effective domain=], or a [=is a registrable domain suffix of or is equal to|registrable domain suffix=] of the [=determines the set of origins on which the public key credential may be exercised|origin=]'s [=effective domain=].
+
+This can make deployment challenging for large environments where multiple country-specific domains are in use (e.g. example.com vs example.co.uk vs example.sg), where vanity or brand domains are required (e.g. myexampletravel.com vs examplecruises.com), and/or where platform as a service providers are used to support mobile apps. 
+
+[=[WRPS]=] can opt in to allowing [=WebAuthn Clients=] to enable a credential to be created and used across a limited set of related [=origin|origins=]
+
+Relying Parties MUST choose a common [=RP ID=] to use across all ceremonies from related origins.
 
+A JSON document MUST be hosted at the `webauthn` well-known URL ([[!RFC8615]]) for the [=RP ID=]. The JSON document MUST be returned as follows:
+
+    - the content type must be `application/json`
+    - JSON document MUST contain a single object named `origins`
+    - the `origins` object MUST contain an array of one or more web origins
+
+For example, for the RP ID `example.com`:
+
+<xmp class="json" highlight="json">
+{
+    "origins": [
+        "https://example.co.uk",
+        "https://example.de",
+        "https://example.sg"
+        "https://myexamplerewards.com"
+    ]
+}
+</xmp>
+
+[=WebAuthn Clients=] supporting this feature MUST support at least five [=origin labels=]. Client policy SHOULD define an upper limit to prevent abuse.
+
+[=WebAuthn Clients=] supporting this feature SHOULD include {{ClientCapability/relatedOriginRequests}} in their response to [[#sctn-getClientCapabilities|getClientCapabilities()]].
 
 # WebAuthn <dfn>Authenticator Model</dfn> # {#sctn-authenticator-model}
 
@@ -8616,6 +8708,11 @@ For example:
     {{CollectedClientData/origin}} to exactly equal some element of a list of allowed origins,
     for example the list <code>["https://example.org", "https://login.example.org"]</code>.
 
+- A web application leveraging [[#sctn-related-origins|related origin requests]] might also require
+    {{CollectedClientData/origin}} to exactly equal some element of a list of allowed origins,
+    for example the list <code>["https://example.co.uk", "https://example.de", "https://myexamplerewards.com"]</code>.
+    This list will typically match the origins listed in the well-known URI for the [=RP ID=]. See [[#sctn-related-origins]].
+
 - A web application served at a large set of domains that changes often might parse
     {{CollectedClientData/origin}} structurally and require that the URL scheme is <code>https</code>
     and that the authority equals or is any subdomain of the [=RP ID=] - for example,