Revisions

thomascavanagh-okta · thomascavanagh-okta · commit be89eef2c9b0 · 2025-11-17T14:15:10.000-05:00
diff --git a/packages/@okta/vuepress-site/docs/guides/custom-passkeys/main/index.md b/packages/@okta/vuepress-site/docs/guides/custom-passkeys/main/index.md
@@ -4,7 +4,7 @@ excerpt: Learn how to customize passkeys with custom domains.
 layout: Guides
 ---
 
-This guide explains how to configure the FIDO2 (WebAuthn) authenticator to allow a single passkey to be used across multiple domains.
+This guide explains different methods for configuring the FIDO2 (WebAuthn) authenticator to allow a single passkey to be used across multiple domains.
 
 ---
 
@@ -20,27 +20,40 @@ Learn how to configure passkeys with multiple domains.
 
 ---
 
-## Passkeys and custom domains
+## What are passkeys
 
-Passkeys are based on the [FIDO2 Web Authentication (WebAuthn) standard](https://fidoalliance.org/fido2-2/fido2-web-authentication-webauthn/). WebAuthn credentials can exist on multiple devices, such as phones, tablets, or laptops, and across multiple operating system platforms. Passkeys enable WebAuthn credentials to be backed up and synchronized across devices.
+Passkeys are based on the [FIDO2 Web Authentication (WebAuthn) standard](https://fidoalliance.org/fido2-2/fido2-web-authentication-webauthn/). WebAuthn credentials can exist on multiple devices, such as phones, tablets, or laptops, and across multiple operating system platforms. The WebAuthn credentials include biometric data, such as fingerprints or facial recognition. Passkeys enable WebAuthn credentials to be backed up and synchronized across devices.
 
 Passkey credentials are cryptographically bound to a specific domain, known as the [Relying Party ID (RP ID)](https://www.w3.org/TR/webauthn/#relying-party-identifier).
 
 > **Note:** You can use passkeys in your org through the [WebAuthn authenticator](https://help.okta.com/okta_help.htm?type=oie&id=csh-configure-webauthn).
 
-### Why use passkeys
+To create a seamless experience where one passkey can work across multiple domains, you can set up your org to use a single, unified RP ID and, for different custom domains, establish a trust relationship between them.
 
-For orgs that operate multiple brands or have different subdomains for their apps, passkeys can provide a streamlined sign-in experience for end users. For example, your users can access various apps with a passkey when they set up a passkey with the `example.com` domain. However, if a user needs to access another app associated with a subdomain, `app1.example.com`, for example, that same passkey won't work by default. The original passkey is only valid for the domain where it was created.
+## Understand custom domains and passkeys
 
-To create a seamless experience where one passkey works across multiple domains, you can set up your org to use a single, unified RP ID and, for different custom domains, establish a trust relationship between them.
+When you're configuring passkeys, there are two types of domains to consider:
 
-You can enable passkey sharing by [configuring an RP ID](#use-an-rp-id-for-subdomains) or by using [associated domains](#use-associated-domains-for-different-root-domains).
+* **Root domains**: A root domain is the highest level of a domain name without any subdomain prefix. In the context of passkeys and WebAuthn, root domains serve as the RP ID, which is the domain that passkey credentials are cryptographically tied to. Your org's root domain is `okta.com` by default.
+* **Subdomains**: Subdomains are domains that exist as a subset under a root domain. `okta.com` is your org's root domain, and your org subdomain typically follows this format: `companyname.okta.com`.
 
-## Use an RP ID for subdomains
+If a user creates a passkey when their browser is on `okta.com`, that passkey is only valid for `okta.com`, by default.
 
-This method allows you to share passkeys between subdomains. For example, you can use an RP ID to support passkeys for the `app1.example.com` and `app2.example.com` domains.
+But, you can [create up to three custom domains](/docs/guides/custom-url-domain/main/#about-okta-domain-customization) to allow for [multibrand customizations](/docs/concepts/brands/#what-is-multibrand-customization). With a custom domain, you can replace the default Okta domain (`companyname.okta.com`) with a branded domain (`login.company.com`). You can use this branded custom domain as the RP ID for passkeys for your end users.
 
-Configure your WebAuthn authenticator to use your root domain (`example.com`) as its RP ID. When a user registers a passkey on any subdomain, the passkey is stamped with the `example.com` RP ID.
+## Set up passkeys for multiple domains in different ways
+
+You can enable passkeys to work with multiple domains by using the following methods:
+
+* [Configure an RP ID](#use-an-rp-id-to-share-passkeys-between-multiple-subdomains): This enables end users to sign in with passkeys across subdomains of a single root domain.
+* [Configure associated domains](#use-associated-domains-to-share-passkeys-between-root-domains): This enables end users to sign in with passkeys across different root domains.
+* [Use a combination of both methods](#share-passkeys-across-okta-and-custom-domains): This enables end users to sign in with passkeys across all domains, including custom domains and Okta's default domains.
+
+### Use an RP ID to share passkeys between multiple subdomains
+
+In this scenario, you want to enable users to sign in to `login.globex.com` and `support.globex.com` domains with a passkey. Create a new RP ID for the WebAuthn authenticator that uses your root domain (`globex.com`). This RP ID works for all subdomains of `globex.com`.
+
+> **Note:** Changing the RP ID `domain` invalidates all existing passkeys for all users. You must notify your users that they need to re-enroll their passkeys if you replace an existing RP ID.
 
 Before you create an RP ID, retrieve the `authenticatorId` of the WebAuthn authenticator with the [List all authenticators](hhttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/Authenticator/#tag/Authenticator/operation/listAuthenticators) endpoint. Ensure that you also have the domain that you want to use as your RP ID set up as a [custom domain](/docs/guides/custom-url-domain).
 
@@ -50,7 +63,7 @@ Then, use the [Replace an authenticator method endpoint](https://developer.okta.
 1. In the path parameters, set the following values:
    * Use the WebAuthn `authenticatorId`.
    * Set `webauthn` as the `methodType`.
-1. Set your domain name as the `rpId.domain.name`. For example, `example.com`.
+1. Set your domain name as the `rpId.domain.name`. For example, set the `name` as `globex.com`.
 1. Send the request.
 
 ```bash
@@ -66,7 +79,7 @@ curl -i -X PUT \
     "attachment": "ANY",
     "rpId": {
       "domain": {
-        "name": "example.com"
+        "name": "globex.com"
       },
       "enabled": false
     },
@@ -75,104 +88,84 @@ curl -i -X PUT \
 }'
 ```
 
-### User experience
+#### User experience
 
-When a user registers a passkey on any subdomain (`app1.example.com`, for example), the passkey is created with the RP ID of `example.com`. When that user signs in to another subdomain (`app2.example.com`, for example), the browser sees that the passkey's RP ID (`example.com`) matches the root domain of the subdomain (`app2.example.com`). The browser allows the authentication to proceed.
+When a user signs in to `login.globex.com` and registers a passkey, the passkey is created with the RP ID of `globex.com`. When that user signs in to `support.globex.com`, for example, the browser sees that the passkey's RP ID (`globex.com`) matches the root domain of the subdomain (`support.globex.com`). The browser allows the authentication to proceed.
 
-## Use associated domains for different root domains
+### Use associated domains to share passkeys between root domains
 
-This method lets you share passkeys between different root domains, such as `example.com`, `examplegames.com`, or your org domain (`example.okta.com`).
+In this scenario, you want users with a passkey that's created with the `globex.com` RP ID to also be able to sign in to `globex-apac.com`. This method enables end users to sign in to those root domains with the same passkey.
 
-Configure your primary brand to trust additional domains using the [Associated Domain Customizations API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/AssociatedDomainCustomizations/). When a user attempts to authenticate on a secondary domain, the browser checks the `/.well-known/webauthn` file on your primary domain. If the secondary domain is listed, the authentication continues.
+Configure your primary brand to trust another domain using the [Associated Domain Customizations API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/AssociatedDomainCustomizations/). When a user attempts to authenticate on a secondary domain, the browser checks the `/.well-known/webauthn` file on your primary domain. If the secondary domain is listed, the authentication continues.
 
-Before you begin, make sure you have the `brandId` for your primary brand. Ensure that all domains you want to associate are valid.
+Before you begin, ensure that you have the `brandId` for your primary brand. Ensure that all domains you want to associate are valid.
 
-Then, use the Associated Domain Customizations API to add trusted domains.
+Then, use the [Associated Domain Customizations API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/AssociatedDomainCustomizations/) to configure the other root domains.
 
 1. Use the following request as a template.
-2. In the path parameters, set the value of `brandId` for your primary domain.
-3. Add all trusted domains to the `origins` array.
-4. Send the request.
+1. In the path parameters, set the following values:
+   * Set the value of `brandId` for your primary domain.
+   * Set the value of `path` to `webauthn`.
+1. Add the `https://globex-apac.com` domain to the `origins` array.
+1. Send the request.
 
 ```bash
 curl -i -X PUT \
-  'https://your-org.okta.com/api/v1/brands/{brandId}/well-known-uris/webauthn/customized' \
+  'https://subdomain.okta.com/api/v1/brands/{brandId}/well-known-uris/{path}/customized' \
   -H 'Authorization: YOUR_AUTH_INFO_HERE' \
   -H 'Content-Type: application/json' \
   -d '{
   "representation": {
     "origins": [
-      "https://examplegames.com",
-      "https://example.okta.com"
+      "https://globex-apac.com",
     ]
   }
 }'
 ```
 
-### User experience
-
-When a user presents a passkey from `example.com` on `examplegames.com`, the browser checks the `/.well-known/webauthn` file on `example.com`. If `examplegames.com` is listed, then the user is able to sign in.
+#### User experience
 
-## Use cases for associated domains and RP IDs
+When a user signs in to `globex-apac.com` with a passkey from `globex.com`, the browser checks the `/.well-known/webauthn` file on `globex.com`. If `globex-apac.com` is listed, then the user is able to sign in.
 
-Follow the scenario that matches your organization's needs:
-
-* [Share passkeys between multiple subdomains](#share-passkeys-between-multiple-subdomains): This use case lets you share passkeys between subdomains of a single root domain.
-* [Share passkeys between different root domains](#share-passkeys-between-different-root-domains): This use case lets you share passkeys between different root domains, such as `example.com` and `examplegames.com`.
-* [Share passkeys across Okta and custom domains](#share-passkeys-across-okta-and-custom-domains): This use case lets you share passkeys across all domains, including custom domains and Okta's default domains.
-
-### Share passkeys between multiple subdomains
-
-In this scenario, you want a passkey to work for both `app1.example.com` and `app2.example.com`. You only need to set the Custom RP ID to your root domain.
+### Share passkeys across Okta and custom domains
 
-> **Note:** Changing the RP ID `domain` invalidates all existing passkeys for all users. You must notify your users that they will need to re-enroll their passkeys.
+In this scenario, you want a single passkey to work for `globex.com` (custom root domain), `login.globex.com` and `support.globex.com` (subdomains), `globex-apac.com` (other custom root domain), and `globex.okta.com` (your org domain).
 
-### Share passkeys between different root domains
+Before you begin, ensure that you've done the following:
 
-In this scenario, you want a passkey to work for both `atko.com` and `atkogames.com`.
+* [Set `globex.com` as your primary RP ID](#use-an-rp-id-to-share-passkeys-between-multiple-subdomains). Setting `globex.com` as your primary RP ID automatically covers `globex.com` and all its subdomains, like `login.globex.com`, for example.
+* Ensure that you have the `brandId` for your primary brand and that all domains you want to associate are valid.
 
-This requires using Associated Domains. This guide assumes `atko.com` is your primary brand and login domain.
+Then, use the [Associated Domain Customizations API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/AssociatedDomainCustomizations/) to trust the other root domains.
 
-1. First, complete all steps from **Scenario 1** to set `atko.com` as your primary RP ID.
-1. Find the `brandId` associated with your primary domain (`atko.com`).
-1. Send a `PUT` request to the Associated Domain Customizations API, listing your other root domain in the `origins` array.
+1. Use the following request as a template.
+1. In the path parameters, set the following values:
+   * Set the value of `brandId` for your primary domain.
+   * Set the value of `path` to `webauthn`.
+1. Add `https://globex-okta.com` to the `origins` array.
+1. Send the request.
 
-```json
-{
+```bash
+curl -i -X PUT \
+  'https://subdomain.okta.com/api/v1/brands/{brandId}/well-known-uris/{path}/customized' \
+  -H 'Authorization: YOUR_AUTH_INFO_HERE' \
+  -H 'Content-Type: application/json' \
+  -d '{
   "representation": {
     "origins": [
-      "https://atkogames.com"
+      "https://globex.okta.com",
     ]
   }
-}
+}'
 ```
 
-Now, when a user on `atkogames.com` tries to authenticate, your app will request a passkey for `rpId: "atko.com"`. The browser will check `https.://atko.com/.well-known/webauthn`, see `atkogames.com` in the `origins` list, and allow the authentication.
-
-### Share passkeys across Okta and custom domains
-
-In this scenario, you want a single passkey to work for `atko.com` (root), `app1.atko.com` (subdomain), `atkogames.com` (different root), and `atko.okta.com` (your org domain).
+> **Note:** While you can explicitly add subdomains like `https://login.globex.com` to the `origins` list, it's not required. The browser's subdomain policy already covers them.
 
-This is a comprehensive solution that combines the previous two scenarios.
-
-1. First, complete all steps from **Scenario 1** to set `atko.com` as your primary RP ID. This step automatically covers `atko.com` and all its subdomains (like `app1.atko.com`).
-1. Find the `brandId` associated with your primary domain (`atko.com`).
-1. Send a `PUT` request to the Associated Domain Customizations API, listing all other domains that are *not* subdomains of your primary RP ID.
-
-```json
-{
-  "representation": {
-    "origins": [
-      "https://atkogames.com",
-      "https://atko.okta.com"
-    ]
-  }
-}
-```
+#### User experience
 
-> **Note:** While you can explicitly add subdomains like `https://app1.atko.com` to the `origins` list, it's not required. The browser's native subdomain policy (from Step 1) already covers them.
+When a user registers a passkey on any of the listed domains, the passkey is created with the RP ID of `globex.com`. The browser recognizes that the passkey's RP ID matches the root domain for `login.globex.com` and trusts the other associated domains. `globex-apac.com` and `globex.okta.com` are trusted because they're listed in the `/.well-known/webauthn` file.
 
-With this configuration, a single passkey registered with the `atko.com` RP ID is now trusted and can be used across your entire brand ecosystem.
+With this configuration, a single passkey registered with the `globex.com` RP ID is now trusted and can be used across your entire brand ecosystem.
 
 ## See also
 
