diff --git a/main/config/navigation/universal-components.json b/main/config/navigation/universal-components.json index e39e05c905..9429c14f0a 100644 --- a/main/config/navigation/universal-components.json +++ b/main/config/navigation/universal-components.json @@ -26,6 +26,14 @@ "docs/get-started/universal-components/web/components/sso-provider-create", "docs/get-started/universal-components/web/components/sso-provider-edit" ] + }, + { + "group": "My Account", + "pages": [ + "docs/get-started/universal-components/web/components/my-account-overview", + "docs/get-started/universal-components/web/components/user-mfa-management", + "docs/get-started/universal-components/web/components/user-passkey-management" + ] } ] } diff --git a/main/docs/get-started/universal-components/web/components/my-account-overview.mdx b/main/docs/get-started/universal-components/web/components/my-account-overview.mdx new file mode 100644 index 0000000000..7d83c87115 --- /dev/null +++ b/main/docs/get-started/universal-components/web/components/my-account-overview.mdx @@ -0,0 +1,367 @@ +--- +title: Build a Self-Service Account Security Interface with My Account API +description: Learn how to configure Universal Components to build self-service account security interfaces with My Account API. +sidebarTitle: Build Account Security UI +--- + +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx"; + + + +My Account components allow you to embed a self-service authentication management interface directly into your web application. Your users can enroll and remove multi-factor authentication (MFA) factors and manage passkeys within your web application. + +## How it works + +My Account components use the My Account API's [authentication methods](/docs/manage-users/my-account-api#manage-authentication-methods) endpoints to render an authentication-management UI inside your application. + + +The [My Account API](/docs/manage-users/my-account-api) currently enforces low [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations), especially on free-tier tenants. This may cause errors while using these components. + + +When an authenticated user opens their account settings screen, the Auth0 SDK retrieves an [access token](/docs/secure/tokens/access-tokens) scoped to the My Account API audience. + +The components use this token to call the My Account API [`/me/v1/authentication-methods`](/docs/api/myaccount/authentication-methods/get-authentication-methods) as the logged-in user, so each user can only view and modify their own authentication methods. + +### Available components + +| **Component** | **API endpoint** | +| :--- | :--- | +| [**UserMFAMgmt**](/docs/get-started/universal-components/web/components/user-mfa-management) Enroll and delete MFA factors: email OTP, SMS OTP, TOTP (authenticator application), push notifications, passkeys, and recovery codes. | `/me/v1/authentication-methods` | +| [**UserPasskeyMgmt**](/docs/get-started/universal-components/web/components/user-passkey-management) Register and revoke WebAuthn passkeys. | `/me/v1/authentication-methods` (type: passkey) | + + +* These components create **end-user self-service** interfaces. End users can enroll, list, and remove every authentication method on their own account: email OTP, SMS OTP, TOTP (authenticator application), push notifications, passkeys, and recovery codes. +* For **delegated admin** interfaces in which a user manages an Auth0 [Organization](/docs/manage-users/organizations), read [Build a Delegated Admin Interface](/docs/get-started/universal-components/web/components/build-delegated-admin). + + + + + + +## Prerequisites + +### Enable My Account API + +1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis). +2. Select **Activate My Account API** to enable it for your tenant. + +### Create the application and configure My Account API permissions + +1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**. +2. Select **Single Page Web Applications**. +3. Select the **Settings** tab and add your **Callback, Logout, and Web Origins URLs**. For example: `http://localhost:5173`. +4. Select the **API Access** tab. +5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions: + + `create:me:authentication_methods` + `read:me:authentication_methods` + `update:me:authentication_methods` + `delete:me:authentication_methods` + `read:me:factors` + +6. Select **Save** to save the permissions. + + +* The user’s access token only includes permissions that were granted during login. +* Request all five scopes to allow users to enroll, review, and remove authentication methods. + + +### Set up the database and test user + +1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection. +2. In the **Applications** tab of the database, enable your application. +3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users). +4. Select **Create User** to create a user assigned to the new database connection. +5. Select **Create** to add the new user; use this new user for testing. + +## Configure your application + +### Install the component + + +```bash pnpm wrap lines +pnpm add @auth0/universal-components-react +``` + +```bash npm wrap lines +npm install @auth0/universal-components-react +``` + + + +The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + +### Configure environment variables + +Create a `.env` file in your project root: + +```bash wrap lines +VITE_AUTH0_DOMAIN=YOUR_TENANT_DOMAIN.auth0.com +VITE_AUTH0_CLIENT_ID=YOUR_SPA_CLIENT_ID +``` + +### Configure Universal Components + +Import `Auth0Provider` and `Auth0ComponentProvider` and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page. + +```tsx App.tsx wrap lines +import { Auth0Provider } from "@auth0/auth0-react"; +import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa"; + +const domain = import.meta.env.VITE_AUTH0_DOMAIN; +const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID; + +export default function App() { + return ( + + + {/* your application */} + + + ); +} +``` + + +* Users must be authenticated before the My Account components are rendered. +* Components automatically load the logged-in user's authentication methods from the My Account API. + + + +You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users. + + + + + + +## Prerequisites + +### Enable My Account API + +1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis). +2. Select **Activate My Account API** to enable it for your tenant. + +### Create the application and configure My Account API permissions + +1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**. +2. Select **Regular Web Application**. +3. Select the **Settings** tab and add your **Allowed Callback, and Allowed Logout URLs**. For example: `http://localhost:3000`. +4. Select the **API Access** tab. +5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions: + + `create:me:authentication_methods` + `read:me:authentication_methods` + `update:me:authentication_methods` + `delete:me:authentication_methods` + `read:me:factors` + +6. Select **Save** to save the permissions. + + +* The user’s access token only includes permissions that were granted during login. +* Request all five scopes to allow users to enroll, review, and remove authentication methods. + + +### Set up the database and test user + +1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection. +2. In the **Applications** tab of the database, enable your application. +3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users). +4. Select **Create User** to create a user assigned to the new database connection. +5. Select **Create** to add the new user; use this new user for testing. + +## Configure your application + +### Install the component + + +```bash pnpm wrap lines +pnpm add @auth0/universal-components-react +``` + +```bash npm wrap lines +npm install @auth0/universal-components-react +``` + + + +The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + +### Configure environment variables + +Create a `.env.local` file in your Next.js project root: + +```js wrap lines +NEXT_PUBLIC_AUTH0_DOMAIN=YOUR_TENANT_DOMAIN.auth0.com +NEXT_PUBLIC_AUTH0_CLIENT_ID=YOUR_RWA_CLIENT_ID +AUTH0_SECRET=YOUR_AUTH0_SECRET +AUTH0_ISSUER_BASE_URL="https://YOUR_TENANT_DOMAIN.auth0.com" +``` + +For complete Next.js SDK setup, read the [Auth0 Next.js SDK documentation](/docs/quickstart/webapp/nextjs). + +### Configure Universal Components + +Add `Auth0ComponentProvider` from the `/rwa` subpath to your root layout and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page. + +```tsx app/layout.tsx wrap lines +import { Auth0ComponentProvider } from "@auth0/universal-components-react/rwa"; + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + + {children} + + + + ); +} +``` + + +* Users must be authenticated before the My Account components are rendered. +* Components automatically load the logged-in user's authentication methods from the My Account API. + + + +You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users. + + + + + + +## Prerequisites + +### Enable My Account API + +1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis). +2. Select **Activate My Account API** to enable it for your tenant. + +### Create the application and configure My Account API permissions + +1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**. +2. Select **Single Page Web Applications**. +3. Select the **Settings** tab and add your **Callback, Logout, and Web Origins URLs**. For example: `http://localhost:5173`. +4. Select the **API Access** tab. +5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions: + + `create:me:authentication_methods` + `read:me:authentication_methods` + `update:me:authentication_methods` + `delete:me:authentication_methods` + `read:me:factors` + +6. Select **Save** to save the permissions. + + +* The user’s access token only includes permissions that were granted during login. +* Request all five scopes to allow users to enroll, review, and remove authentication methods. + + +### Set up the database and test user + +1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection. +2. In the **Applications** tab of the database, enable your application. +3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users). +4. Select **Create User** to create a user assigned to the new database connection. +5. Select **Create** to add the new user; use this new user for testing. + +## Configure your application + +### Install the component + +Run the shadcn CLI to add the components directly to your project source: + +```bash MFA management wrap lines +npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json +``` + +```bash Passkey management wrap lines +npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-passkey-management.json +``` + + +The install command adds the component source into `src/components/auth0/my-account/` along with all UI dependencies and the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + + +### Configure environment variables + +Create a `.env.local` file in your project root: + +```js wrap lines +VITE_AUTH0_DOMAIN=YOUR_TENANT.auth0.com +VITE_AUTH0_CLIENT_ID=YOUR_SPA_CLIENT_ID +``` + +### Configure Universal Components + +Import `Auth0Provider` and `Auth0ComponentProvider` and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page. + + +```tsx App.tsx wrap lines +import { Auth0Provider } from "@auth0/auth0-react"; +import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa"; + +const domain = import.meta.env.VITE_AUTH0_DOMAIN; +const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID; + +export default function App() { + return ( + + + {/* your application */} + + + ); +} +``` + + +* Users must be authenticated before the My Account components are rendered. +* Components automatically load the logged-in user's authentication methods from the My Account API. + + + +You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users. + + + + + +## Learn more + + + + MFA factors reference: props, customization, TypeScript definitions, and advanced subcomponents. + + + + Passkey management reference: hooks, message overrides, and CSS class targets. + + + diff --git a/main/docs/get-started/universal-components/web/components/user-mfa-management.mdx b/main/docs/get-started/universal-components/web/components/user-mfa-management.mdx new file mode 100644 index 0000000000..e8c3a45d7f --- /dev/null +++ b/main/docs/get-started/universal-components/web/components/user-mfa-management.mdx @@ -0,0 +1,821 @@ +--- +title: User MFA Management +description: Learn how to render a card-based UI that lets users enroll, view, and delete their own multi-factor authentication factors using the My Account API. +sidebarTitle: UserMFAMgmt component +--- + +import { ComponentLoader } from "/snippets/ComponentLoader.jsx"; +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx"; + + + +The `UserMFAMgmt` component lets users enroll, view, and delete their own multi-factor authentication factors in a single card-based interface using the [My Account API](/docs/manage-users/my-account-api). + +It uses the My Account API’s [authentication methods](/docs/manage-users/my-account-api#manage-authentication-methods) management capabilities to render a complete UI for managing a user’s authentication methods. + +With the `UserMFAMgmt` component, you do not need to orchestrate navigation, call API endpoints, or manage [state](/docs/api/authentication/authorization-code-flow/authorize-application#param-state). + +## Supported factors + +The component handles every authentication method factor configured with the My Account API. + +| **Factor** | **What the component renders** | +|-----------|-------------------------------| +| [Email OTP](/docs/secure/multi-factor-authentication/configure-mfa-email) | Email input → 6-digit OTP verification | +| [SMS OTP](/docs/secure/multi-factor-authentication/configure-sms-notifications-for-mfa) | Country-code picker + phone entry → 6-digit OTP verification | +| [TOTP (Authenticator application)](/docs/secure/multi-factor-authentication/configure-otp) | QR code with manual-entry key → 6-digit OTP verification | +| [Push notifications](/docs/secure/multi-factor-authentication/enable-push-notifications-for-mfa) | QR code for [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian) scan → "waiting for approval" state | +| [Passkeys](/docs/get-started/universal-components/web/components/user-passkeys-management) | Educational screen → OS biometric prompt → enrolled entry in the list | +| [Recovery codes](/docs/secure/multi-factor-authentication/configure-recovery-codes-for-mfa) | Display-once code list with a copy action and an "I've saved my codes" confirmation | + +## Configure your application + +Select your framework to configure environment variables and universal components. + + + + +## Setup requirements + +Before rendering the `UserMFAMgmt` component, follow [Build Account Security UI](/docs/get-started/universal-components/web/components/my-account-overview) to configure your Auth0 tenant and applications. + +### Enable MFA methods and scopes + +**Enable MFA methods** + +1. Navigato to [**Dashboard > Security > Multi-factor Auth**](https://manage.auth0.com/dashboard/*/security/mfa). +2. Enable the desired factors. To learn more, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors#multi-factor-authentication-factors). + +**Add My Account API scopes** + +Add the following My Account API scopes to your [application](/docs/get-started/universal-components/web/components/my-account-overview#create-the-application-and-configure-my-account-api-permissions): +- `enroll:authencicators` +- `remove:authenticators` + +## Install the component + + +```bash pnpm wrap lines +pnpm add @auth0/universal-components-react +``` + +```bash npm wrap lines +npm install @auth0/universal-components-react +``` + + + +The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + +## Get started + +```tsx wrap lines +import { UserMFAMgmt } from "@auth0/universal-components-react"; + +export function SecurityPage() { + return ; +} +``` + + +- Components are always imported from the root entry `@auth0/universal-components-react`, regardless of framework. +- Only the `Auth0ComponentProvider` component uses a framework-specific subpath: `/spa` for React applications, `/rwa` for Next.js applications. + + + +```tsx wrap lines +import React from "react"; +import { UserMFAMgmt } from "@auth0/universal-components-react"; +import { Auth0Provider } from "@auth0/auth0-react"; +import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa"; +import { analytics } from "./lib/analytics"; + +function SecurityPage() { + return ( +
+ { + analytics.track("MFA Factor Enrolled"); + }} + onDelete={() => { + analytics.track("MFA Factor Deleted"); + }} + onErrorAction={(error, action) => { + console.error(`MFA ${action} failed:`, error.message); + }} + onBeforeAction={async (action, factorType) => { + if (action === "delete") { + return await confirmDialog( + `Remove your ${factorType} authenticator?` + ); + } + return true; + }} + customMessages={{ + title: "Two-Factor Authentication", + description: "Manage the extra verification methods used to protect your account.", + }} + styling={{ + variables: { + light: { "--color-primary": "#4f46e5" }, + dark: { "--color-primary": "#818cf8" }, + }, + }} + /> +
+ ); +} + +export default function App() { + const domain = "YOUR_TENANT.auth0.com"; + const clientId = "YOUR_CLIENT_ID"; + + return ( + + + + + + ); +} +``` + + + + + + +## Setup requirements + +Before rendering the `UserMFAMgmt` component, follow [Build Account Security UI](/docs/get-started/universal-components/web/components/my-account-overview) to configure your Auth0 tenant and applications. + +### Enable MFA methods and scopes + +**Enable MFA methods** + +1. Navigato to [**Dashboard > Security > Multi-factor Auth**](https://manage.auth0.com/dashboard/*/security/mfa). +2. Enable the desired factors. To learn more, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors#multi-factor-authentication-factors). + +**Add My Account API scopes** + +Add the following My Account API scopes to your [application](/docs/get-started/universal-components/web/components/my-account-overview#create-the-application-and-configure-my-account-api-permissions): +- `enroll:authencicators` +- `remove:authenticators` + +## Install the component + + +```bash pnpm wrap lines +pnpm add @auth0/universal-components-react +``` + +```bash npm wrap lines +npm install @auth0/universal-components-react +``` + + + +The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + +## Get started + +```tsx app/security/page.tsx wrap lines +"use client"; + +import { UserMFAMgmt } from "@auth0/universal-components-react"; + +export default function SecurityPage() { + return ; +} +``` + + +```tsx app/security/page.tsx wrap lines +"use client"; + +import { UserMFAMgmt } from "@auth0/universal-components-react"; +import { analytics } from "@/lib/analytics"; + +export default function SecurityPage() { + return ( +
+ { + analytics.track("MFA Factor Enrolled"); + }} + onDelete={() => { + analytics.track("MFA Factor Deleted"); + }} + onErrorAction={(error, action) => { + console.error(`MFA ${action} failed:`, error.message); + }} + customMessages={{ title: "Two-Factor Authentication" }} + styling={{ + variables: { + light: { "--color-primary": "#4f46e5" }, + dark: { "--color-primary": "#818cf8" }, + }, + }} + /> +
+ ); +} +``` + + + + + + +## Setup requirements + +Before rendering the `UserMFAMgmt` component, follow [Build Account Security UI](/docs/get-started/universal-components/web/components/my-account-overview) to configure your Auth0 tenant and applications. + +### Enable MFA methods and scopes + +**Enable MFA methods** + +1. Navigato to [**Dashboard > Security > Multi-factor Auth**](https://manage.auth0.com/dashboard/*/security/mfa). +2. Enable the desired factors. To learn more, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors#multi-factor-authentication-factors). + +**Add My Account API scopes** + +Add the following My Account API scopes to your [application](/docs/get-started/universal-components/web/components/my-account-overview#create-the-application-and-configure-my-account-api-permissions): +- `enroll:authencicators` +- `remove:authenticators` + +## Install the component + +```bash wrap lines +npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json +``` + + +The install command adds the component source into `src/components/auth0/my-account/` along with all UI dependencies and the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration. + + +## Get started + +```tsx wrap lines +import { UserMFAMgmt } from "@/components/auth0/my-account/user-mfa-management"; + +export function SecurityPage() { + return ; +} +``` + + +```tsx wrap lines +import React from "react"; +import { UserMFAMgmt } from "@/components/auth0/my-account/user-mfa-management"; +import { Auth0Provider } from "@auth0/auth0-react"; +import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa"; +import { analytics } from "./lib/analytics"; + +function SecurityPage() { + return ( +
+ { + analytics.track("MFA Factor Enrolled"); + }} + onDelete={() => { + analytics.track("MFA Factor Deleted"); + }} + onErrorAction={(error, action) => { + console.error(`MFA ${action} failed:`, error.message); + }} + onBeforeAction={async (action, factorType) => { + if (action === "delete") { + return await confirmDialog(`Remove your ${factorType} authenticator?`); + } + return true; + }} + customMessages={{ title: "Two-Factor Authentication" }} + styling={{ + variables: { + light: { "--color-primary": "#4f46e5" }, + dark: { "--color-primary": "#818cf8" }, + }, + }} + /> +
+ ); +} + +export default function App() { + const domain = "YOUR_TENANT.auth0.com"; + const clientId = "YOUR_CLIENT_ID"; + + return ( + + + + + + ); +} +``` + + + + + +## Props + +### Display props + +Display props control how the component renders without affecting its behavior. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropTypeDefaultDescription
hideHeaderbooleanfalseHide the component header (title and description).
readOnlybooleanfalseDisable all mutation actions (enroll and delete). Factors are shown but cannot be added or removed.
showActiveOnlybooleanfalseShow only factor types that the user has at least one active enrollment for. Factor types with no enrollments are hidden.
disableEnrollbooleanfalseHide the enroll button for all factor types. Users can still delete existing factors.
disableDeletebooleanfalseHide the delete button on all enrolled factor rows. Users can still enroll new factors.
factorConfigPartial
<Record<MFAType,
{ visible?: boolean;
enabled?: boolean }>>		{}Per-factor-type visibility and enabled state.
+ + +**factorConfig** + +Use `factorConfig` to show or grey-out specific factor types without editing the tenant configuration. +Each key is a factor type `string`; both fields are optional and default to `true`. + +Supported factor type keys: `sms`, `otp`, `email`, `push-notification`, `webauthn-platform`, `webauthn-roaming`, `recovery-code`. + +- `visible` render the factor row in the list (`false` to hide). +- `enabled` render the factor row is interactive (`false` renders it greyed-out and non-interactive). + +```tsx wrap lines +