Django Two-Factor Auth 配置详解：构建安全的双因素认证系统

Django Two-Factor Auth 配置详解：构建安全的双因素认证系统

django-two-factor-auth 项目地址: https://gitcode.com/gh_mirrors/dja/django-two-factor-auth

前言

在当今网络安全环境中，双因素认证(2FA)已成为保护用户账户安全的重要措施。Django Two-Factor Auth项目为Django应用提供了完整的双因素认证解决方案。本文将深入解析该项目的配置选项，帮助开发者构建更安全的认证系统。

基础配置

核心设置项

TWO_FACTOR_PATCH_ADMIN (默认: True)

• 控制是否修改Django admin使用自定义登录视图
• 注意：当前admin界面不会强制管理员用户设置OTP

LOGIN_URL

• 必须指向本项目提供的登录视图
• 该视图处理密码认证及OTP验证流程

LOGIN_REDIRECT_URL

• 用户登录后重定向的URL
• 项目提供了基础的账户管理页面，但可自定义

LOGOUT_REDIRECT_URL

• 用户登出后重定向的URL

二维码生成配置

TWO_FACTOR_QR_FACTORY

• 控制二维码生成方式
• 默认使用SVG格式(无额外依赖，但不支持IE8及以下)
• 可选PIL/Pillow(PNG格式)或pyimaging

TOTP设置

TWO_FACTOR_TOTP_DIGITS (默认: 6)

• TOTP令牌位数(6或8位)
• 注意：Google Authenticator不支持8位码

TWO_FACTOR_LOGIN_TIMEOUT (默认: 600秒)

• 用户完成密码验证后允许完成2FA的时间窗口
• 设为0禁用超时

电话验证配置

要启用电话验证，需添加'two_factor.plugins.phonenumber'到INSTALLED_APPS

TWO_FACTOR_CALL_GATEWAY

• 电话验证网关
• 内置选项：
  • Twilio(真实电话验证)
  • Fake(开发用，记录日志)

TWO_FACTOR_SMS_GATEWAY

• 短信验证网关
• 选项同上

PHONENUMBER_DEFAULT_REGION

• 电话号码解析的默认地区
• 设置后可不输入国家代码

TWO_FACTOR_PHONE_THROTTLE_FACTOR (默认: 1)

• 失败尝试的限流系数
• 设为0禁用限流

邮件验证配置

要启用邮件验证，需添加'django_otp.plugins.otp_totp'到INSTALLED_APPS

确保DEFAULT_FROM_EMAIL设置正确，可自定义邮件主题、内容等。

Twilio网关配置

1. 安装Twilio客户端：

pip install twilio

2. 添加URL配置：

from two_factor.gateways.twilio.urls import urlpatterns as tf_twilio_urls

urlpatterns = [
    path('', include(tf_twilio_urls)),
    ...
]

3. 启用中间件：

MIDDLEWARE = (
    ...
    'django_otp.middleware.OTPMiddleware',
    'two_factor.middleware.threadlocals.ThreadLocals',
)

WebAuthn配置

WebAuthn支持生物识别、安全密钥等现代认证方式。

核心设置：

TWO_FACTOR_WEBAUTHN_RP_NAME (必需)

• 应用名称标识符

设备限制：

TWO_FACTOR_WEBAUTHN_AUTHENTICATOR_ATTACHMENT

• 认证设备类型限制(platform/cross-platform)

TWO_FACTOR_WEBAUTHN_PREFERRED_TRANSPORTS

• 首选通信方式(如['usb', 'internal'])

验证级别：

TWO_FACTOR_WEBAUTHN_UV_REQUIREMENT (默认: 'discouraged')

• 用户验证要求级别

认证配置：

TWO_FACTOR_WEBAUTHN_ATTESTATION_CONVEYANCE (默认: 'none')

• 认证信息传递级别

TWO_FACTOR_WEBAUTHN_PEM_ROOT_CERTS_BYTES_BY_FMT

• 根证书配置，用于认证验证

实体配置：

TWO_FACTOR_WEBAUTHN_ENTITIES_FORM_MIXIN

• 自定义WebAuthn实体构建方式

TWO_FACTOR_WEBAUTHN_RP_ID

• 依赖方域名设置

限流：

TWO_FACTOR_WEBAUTHN_THROTTLE_FACTOR (默认: 1)

• 失败尝试限流系数

浏览器记忆功能

允许用户在特定浏览器上免去二次验证。

TWO_FACTOR_REMEMBER_COOKIE_AGE (默认: None)

• 记忆时长(秒)，设为None禁用

Cookie配置：

• TWO_FACTOR_REMEMBER_COOKIE_PREFIX: 前缀(默认'remember-cookie_')
• TWO_FACTOR_REMEMBER_COOKIE_DOMAIN: 域名
• TWO_FACTOR_REMEMBER_COOKIE_PATH: 路径(默认'/')
• TWO_FACTOR_REMEMBER_COOKIE_SECURE: 仅HTTPS(默认False)
• TWO_FACTOR_REMEMBER_COOKIE_HTTPONLY: HttpOnly标志(默认True)
• TWO_FACTOR_REMEMBER_COOKIE_SAMESITE: SameSite策略(默认'Lax')

最佳实践建议

1. 生产环境应使用Twilio等专业服务而非Fake网关
2. 根据用户群体选择合适的TOTP位数
3. WebAuthn配置应结合实际安全需求
4. 浏览器记忆功能需权衡便利性与安全性
5. 所有敏感配置应通过环境变量管理

通过合理配置Django Two-Factor Auth，开发者可以为应用构建灵活而强大的双因素认证系统，有效提升账户安全性。

django-two-factor-auth 项目地址: https://gitcode.com/gh_mirrors/dja/django-two-factor-auth