Improve WellKnownWebAuthnView reference docs based on feedback; combine content in PR#73, thereby creating a how-to guide section; guide on how to configure for related origins; move the guides in Customizing behavior to the how-to guide section

activus-d · activus-d · commit 8ca078410a5e · 2025-05-27T13:04:10.000+01:00
diff --git a/docs/customizing_behavior.rst b/docs/customizing_behavior.rst
@@ -45,12 +45,3 @@ Customizing frontend
 --------------------
 
 The frontend implementation in this library supports customization only through CSS. For any additional customization, you have to create your own implementation. As long as you call the same API endpoints and use the same JSON structure, you can still use all other components of this package, including views and models.
-
-
-.. toctree::
-    :maxdepth: 2
-    :hidden:
-
-    Customize views <customize_views.rst>
-    Customize helper class <customize_helper_class.rst>
-    Customize models <customize_models.rst>
diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -9,6 +9,9 @@ Glossary
     authenticator
         An authenticator is a software or hardware implementation of the client side of the Web Authentication standard. It manages the cryptographic parts of the process. When a user registers or logs in with a credential, the browser usually presents several authenticator options. Common examples include Chrome Password Manager, a USB key, iCloud Keychain, or a smartphone.
 
+    country code top-level domain (ccTLD)
+        A specific type of top-level domain (TLD) that is associated with a particular country or territory. It consists of two letters and is used to identify websites related to that country. For example, ".uk" for the United Kingdom or ".de" for Germany.
+
     credential ID
         A unique identifier generated by the authenticator when creating a WebAuthn credential. Credential ID consists of a random sequence of bytes and is used in negotiations between the browser and the server.
 
@@ -34,6 +37,9 @@ Glossary
     relying party
         The entity that relies on the Web Authentication standard to authenticate users. This refers to you, as you are using Web Authentication to authenticate your users.
 
+    relying party ID (rpID)
+        The domain of the website or service where a passkey can be used, without including protocol, port, or path. For example, ``acbde.com``. It ties the passkey to a specific domain to prevent phishing. Subdomains match a parent rpID, but not the other way around. The rpID is included in WebAuthn login requests and verified by the browser against the current page's origin.
+
     resident key
         An alternative term for a for a passkey or resident key. It refers to a WebAuthn credential that allows authentication without the server providing credential IDs.
 
diff --git a/docs/how_to_guides/configure_related_origins.rst b/docs/how_to_guides/configure_related_origins.rst
@@ -0,0 +1,34 @@
+Configure related origins
+=========================
+
+You can use ``WellKnownWebAuthnView`` to configure your application to use the same :term:`WebAuthn credentials <WebAuthn credential>` across multiple domains. For example, if your main application runs on ``https://example.com`` and you have a localized version on ``https://example.co.uk`` and ``https://example.de``.
+
+Set up the URL
+--------------
+
+Modify your ``<project>/urls.py`` file and add the required URL configuration:
+
+.. code-block:: py
+
+    from django.urls import path
+    from django_otp_webauthn.views import WellKnownWebAuthnView
+    urlpatterns = [
+        ...
+        path(".well-known/webauthn", WellKnownWebAuthnView.as_view()),
+    ]
+
+Add related origins to your Django settings
+-------------------------------------------
+
+Now in your ``<project>/settings.py`` file, add your related origins to ``OTP_WEBAUTHN_RP_RELATED_ORIGINS``. The related origins must use ``HTTPS``, except for localhost origins which can use ``HTTP`` for local development:
+
+.. code-block:: py
+
+    OTP_WEBAUTHN_RP_RELATED_ORIGINS = [
+        "https://example.com",
+        "https://example.co.uk",
+        "https://example.de",
+        "https://app.example.com"
+    ]
+
+For more information, see the reference docs on :ref:`WellKnownWebAuthnView <wellknownwebauthnview>`.
diff --git a/docs/how_to_guides/customize_helper_class.rst b/docs/how_to_guides/customize_helper_class.rst
diff --git a/docs/how_to_guides/customize_models.rst b/docs/how_to_guides/customize_models.rst
diff --git a/docs/how_to_guides/customize_views.rst b/docs/how_to_guides/customize_views.rst
diff --git a/docs/how_to_guides/index.rst b/docs/how_to_guides/index.rst
@@ -0,0 +1,12 @@
+How-to guides
+=============
+
+This section provides step-by-step guides to help you implement common use cases and features with Django OTP WebAuthn:
+
+.. toctree::
+    :maxdepth: 1
+
+    Customize views <customize_views.rst>
+    Customize helper class <customize_helper_class.rst>
+    Customize models <customize_models.rst>
+    Configure related origins <configure_related_origins.rst>
diff --git a/docs/index.rst b/docs/index.rst
@@ -61,7 +61,8 @@ Head over to the :ref:`Getting started <getting-started>` section to learn about
    :hidden:
 
    Getting started <getting_started/index.rst>
-   Customizing behavior <customizing_behavior/index.rst>
+   customizing_behavior.rst
+   How-to guides <how_to_guides/index.rst>
    Reference <reference/index.rst>
    glossary.rst
    FAQ <faq.rst>
diff --git a/docs/reference/views.rst b/docs/reference/views.rst
@@ -38,12 +38,65 @@ Finally, the system logs in the user associated with the ``WebAuthnCredential``
 WellKnownWebAuthnView
 ---------------------
 
-``WellKnownWebAuthnView`` supports WebAuthn across related origins.
+``WellKnownWebAuthnView`` supports :term:`WebAuthn` across related origins. The view permits public access, doesn't require authentication, and accepts only ``GET`` requests. It also accepts origins that use ``https`` or ``http://localhost`` for local development, and caches responses for 10 minutes.
 
-The view returns a JSON response containing the list of related origins configured in the ``OTP_WEBAUTHN_RP_RELATED_ORIGINS`` setting. This allows :term:`WebAuthn credentials <WebAuthn credential>` to work across multiple domains that share the same :term:`relying party`.
+Use cases
+~~~~~~~~~
 
-The view permits public access, doesn't require authentication, and accepts only GET requests. Also, Responses are cached for 10 minutes.
+Two use cases necessitate allowing requests from related origins.
 
-You can Configure this view at the ``/.well-known/webauthn`` URL. Define the ``OTP_WEBAUTHN_RP_RELATED_ORIGINS`` setting as a list of secure origins.
+The first use case is deployments that use different :term:`country code top-level domains (ccTLD) <country code top-level domain (ccTLD)>` worldwide. For example, a grocery website might use ``https://grocery.com`` for users in the United States, ``https://grocery.co.uk`` for the United Kingdom, and ``https://grocery.de`` for Germany.
 
-The view accepts only origins that use ``https`` or ``http://localhost`` for local development.
+The second use case is for organizations that offer additional services with different or extended branding and share the same accounts. For example, a grocery website may have a website for taking orders from buyers and a separate website for tracking delivery.
+
+How it works
+~~~~~~~~~~~~
+
+``WellKnownWebAuthnView`` works by allowing a :term:`relying party` to provide a list of valid origins for a given :term:`relying party ID (rpID)`.
+
+During a WebAuthn operation, the browser checks whether the current origin matches the rpID. If the origin and rpID differ, and the client supports related origin requests, the browser queries the ``/.well-known/webauthn`` endpoint hosted at the rpID. The server responds with a JSON document that includes a top-level ``origins`` key, with a list of related origins as its value. The browser verifies the list and continues with authentication if the current origin is included.
+
+The browser processes this list using **labels**. A label refers to the part of the domain directly preceding the top-level domain. For example, ``grocery`` is the label for domains like ``https://grocery.com``, ``https://grocery.co.uk``, and ``https://grocery.de``. This grouping allows browsers to support origin lists efficiently without processing excessive unique entries.
+
+Client implementations shouldn't support more than five labels. So if the list contains 30 domains that all share the label ``grocery``, the browser counts these as a single unique label.
+
+Configuration
+~~~~~~~~~~~~~
+
+To support related origins, define the list of allowed origins in the ``OTP_WEBAUTHN_RP_RELATED_ORIGINS`` setting. Each origin must use ``https``, except for ``http://localhost`` during development.
+
+Also, a JSON document must be hosted at the WebAuthn well-known path for the rpID, ``/.well-known/webauthn``. For example, if the rpID is ``grocery.com``, the full URL would be ``https://grocery.com/.well-known/webauthn``. The server must also respond with a content type of ``application/json``. The JSON response must contain the list of related origins configured in ``OTP_WEBAUTHN_RP_RELATED_ORIGINS`` in the ``<project>/settings.py`` file.
+
+Here is an example configuration in the ``<project>/settings.py`` file:
+
+.. code-block:: py
+
+    OTP_WEBAUTHN_RP_RELATED_ORIGINS = [
+        "https://grocery.com",
+        "https://grocery.co.uk",
+        "https://grocery.de",
+    ]
+
+The JSON response will look like this:
+
+.. code-block:: json
+
+    {
+        "origins": [
+            "https://grocery.com",
+            "https://grocery.co.uk",
+            "https://grocery.de",
+        ]
+    }
+
+Choosing rpID
+~~~~~~~~~~~~~
+
+The most important decision when configuring your application for related origins is choosing a primary rpID. All related origins must use the primary rpID for authentication. You should select the domain most closely tied to your brand, usually the ``.com`` domain.
+
+Existing deployments that already use multiple rpIDs face different challenges. The system must maintain backward compatibility while implementing the related origins feature. Users with passkeys tied to the local rpID can continue normal operations, while those with credentials from other origins require additional steps. The solution requires each existing rpID to serve its well-known WebAuthn document listing all authorized origins. The backend must track which rpID created each passkey through explicit metadata or derived information. The login interface must handle cases where automatic recognition fails by implementing username-based lookup flows that redirect users to the correct authentication endpoint.
+
+Browser compatibility
+~~~~~~~~~~~~~~~~~~~~~
+
+All deployments must account for browser compatibility since not all browsers support related origin requests. The system should detect browser capabilities and provide fallback authentication methods when needed. For the list of supported browsers, see `Matrix <https://passkeys.dev/device-support/#matrix>`_.
