auth0-mfa

Auth0 MFA 指南

添加多重身份验证以保护用户账户，并要求用户在执行敏感操作时进行额外验证。

---

概述

什么是 MFA？

多重身份验证（MFA）要求用户提供两种或更多验证因素才能访问自己的账户。Auth0 支持多种 MFA 因素，并可针对敏感操作启用逐步身份验证。

何时使用此技能

• 添加 MFA 以保护用户账户
• 在执行敏感操作（付款、更改设置）时要求额外验证
• 实现自适应／基于风险的身份验证
• 满足合规要求（PCI-DSS、SOC2、HIPAA）

支持的 MFA 因素

因素	类型	说明
TOTP	持有的物品	基于时间的一次性密码（Google Authenticator、Authy）
SMS	持有的物品	通过短信发送的一次性验证码
Email	持有的物品	通过电子邮件发送的一次性验证码
Push	持有的物品	通过 Auth0 Guardian 应用发送推送通知
WebAuthn	持有的物品／自身特征	安全密钥、生物识别、通行密钥
Voice	持有的物品	通过电话发送的一次性验证码
Recovery Code	备用	仅可使用一次的恢复码

核心概念

概念	说明
acr_values	在身份验证期间请求 MFA
amr 声明	身份验证方法参考——指明用户采用何种方式完成身份验证
逐步身份验证	初次登录后，针对特定操作要求 MFA
自适应 MFA	根据风险信号有条件地要求 MFA

---

步骤 1：在租户中启用 MFA

通过 Auth0 控制面板

1. 前往 Security → Multi-factor Auth
2. 启用所需的因素（TOTP、SMS 等）
3. 配置 Policies：
   • Always - 所有登录都要求 MFA
   • Adaptive - 基于风险的 MFA
   • Never - 禁用 MFA（改用逐步身份验证）

通过 Auth0 CLI

# View current MFA configuration
auth0 api get "guardian/factors"

# Enable TOTP (One-time Password)
auth0 api put "guardian/factors/otp" --data '{"enabled": true}'

# Enable SMS
auth0 api put "guardian/factors/sms" --data '{"enabled": true}'

# Enable Push notifications
auth0 api put "guardian/factors/push-notification" --data '{"enabled": true}'

# Enable WebAuthn (Roaming - Security Keys)
auth0 api put "guardian/factors/webauthn-roaming" --data '{"enabled": true}'

# Enable WebAuthn (Platform - Biometrics)
auth0 api put "guardian/factors/webauthn-platform" --data '{"enabled": true}'

# Enable Email
auth0 api put "guardian/factors/email" --data '{"enabled": true}'

配置 MFA 策略

# Set MFA policy: "all-applications" or "confidence-score"
auth0 api patch "guardian/policies" --data '["all-applications"]'

---

步骤 2：实现逐步身份验证

逐步身份验证会在执行敏感操作时要求 MFA，而不要求每次登录都进行 MFA。

acr_values 参数

在授权请求中加入 acr_values，以请求 MFA：

acr_values=http://schemas.openid.net/pape/policies/2007/06/multi-factor

实现模式

所有框架通用的模式：

1. 检查用户是否已完成 MFA（检查 amr 声明）
2. 如果尚未完成，则通过 acr_values 参数请求 MFA
3. 验证 MFA 后执行敏感操作

完整的框架专属示例，请参阅示例指南：

• React（基础用法和自定义 Hook）
• Next.js（App Router）
• Vue.js
• Angular

---

其他资源

此技能拆分为多个文件，以便更好地组织内容：

逐步身份验证示例

适用于所有框架的完整代码示例：

• React（基础用法和自定义 Hook 模式）
• Next.js（带 API 路由的 App Router）
• Vue.js（组合式 API）
• Angular（服务和组件）

后端验证

了解如何在后端验证 MFA 状态：

• Node.js / Express JWT 验证
• Python / Flask 验证
• 中间件示例

高级主题

高级 MFA 实现模式：

• 使用 Auth0 Actions 实现自适应 MFA
• 根据风险信号有条件地启用 MFA
• MFA Enrollment API

参考指南

常见模式和故障排查：

• 记住 MFA 30 天
• 高价值交易的 MFA
• MFA 状态显示
• 错误处理
• AMR 声明值
• 测试策略
• 安全注意事项

---

相关技能

• auth0-quickstart - Auth0 基础设置
• auth0-passkeys - WebAuthn／通行密钥实现
• auth0-actions - 自定义身份验证逻辑

---

References

• Auth0 MFA Documentation
• Step-Up Authentication
• MFA API
• acr_values Parameter