Django 2FA 使用 Twilio 验证

先决条件

• Python 3.6+
• Twilio帐户
• django2.29+
• twilio7.8.2+
• phonenumbers8.12.26+

安装

使用pip install django-twilio-2fa.

如果安装失败，请尝试pip install --upgrade pip

添加到您的INSTALLED_APPS：

INSTALLED_APPS = (
    ...
    "django_twilio_2fa",
    "django_widget_tweaks",  # only required if using included templates
    ...
)

添加项目urls.py：

urlpatterns = [
    ...
    path(
        "2fa/",  # Can be changed to any path
        include("django_twilio_2fa.urls")
    ),
]

流动

用户仅应在以下情况下进入 2FA 流程：

• 他们需要注册 2FA
• 他们没有以前的 2FA 身份验证
• 他们之前的 2FA 身份验证已过期，需要续订

用户应通过“开始”视图进入流程。如果他们没有注册 2FA，他们将被重定向到注册视图。否则，假定他们的 2FA 身份验证已过期。

如何以及何时进入流程在本项目范围之外确定。但是，其中有示例中间件test_app/middleware.py可以用作参考。

开始

这是 2FA 流程的主要入口点。

如果PHONE_NUMBER_CB返回None（表示用户尚未注册 2FA），用户将被重定向到注册视图。

如果只允许一种方法，则将使用该方法创建验证，并将用户重定向到验证视图。（用户不会看到这个屏幕。）

否则，将向用户呈现验证方法的选择。

此视图的模板：start.html

登记

如果用户尚未注册 2FA 并且ALLOW_REGISTER是True，则将显示此屏幕以向其帐户添加电话号码。

如果用户尚未注册，他们将被重定向到开始视图。

如果ALLOW_REGISTER是False并且没有可用的电话号码，用户将被重定向到失败视图。

如果REGISTER_OPTIONAL是True，则用户可以跳过 2FA 注册。有关更多详细信息，请参阅该设置。

此视图的模板：register.html

REGISTER_OPTIONAL是False	REGISTER_OPTIONAL是True

改变

如果用户已经注册并想要更改他们的电话号码，则会显示此视图。

如果ALLOW_CHANGE或IS_VERIFIEDis False，将向用户显示错误。

它与 register 完全相同，除了is_optionalalways False。

此视图的模板：change.html

核实

发送验证后，用户将在此视图中输入代码。副本会根据使用的方法而改变。

不正确的代码将显示错误消息，并允许用户重试最多 5 次尝试。

如果用户用尽所有尝试，用户将被重定向到“失败”视图。

如果用户没有收到验证，可以点击“还没有收到<>？” 关联。如果超过指定时间，将重新创建验证。（见RETRY_TIME。）

此视图的模板：verify.html

成功

如果没有VERIFY_SUCCESS_URL定义，用户将在成功验证后重定向到此视图。

此视图的模板：success.html

失败的

如果验证失败，用户将被重定向到此视图。

根据`RETRY，用户将能够

此视图的模板：failed.html

用户可以重试验证	用户无法重试验证

设置

所有设置都以TWILIO_2FA_.

任何设置都可以是回调。但是，以 结尾的设置_CB 必须是回调。如果定义了回调设置但不可调用，ValueError则将抛出 a。

ACCOUNT_SID

Twilio 控制台中的 Twilio 帐户 SID。

注意：您不能将测试凭据与验证一起使用。

AUTH_TOKEN

来自 Twilio 控制台的 Twilio 身份验证令牌。

注意：您不能将测试凭据与验证一起使用。

SERVICE_ID

从 Twilio 控制台验证服务 ID。

ALLOWED_METHODS

允许的方法列表。该方法必须在您在 Twilio 控制台中设置的验证服务中启用。

可用方法：sms、call和email。注意：需要 Sendgrid 集成。详细信息可以在这里找到https://www.twilio.com/docs/verify/email#create-an-email-template。whatsappemail

如果设置None或未设置此设置，所有可用的方法都将呈现给最终用户。

PHONE_NUMBER_DEFAULT_REGION

库的默认区域phonenumbers。通常，这是国家/地区代码，但可以在此处找到整个列表。

设置此项允许用户无需使用电话号码输入国家代码。

您可以将其设置None为没有默认区域。

默认US为美国。

PHONE_NUMBER_ALLOWED_COUNTRIES

允许电话号码来源的国家/地区代码列表。

默认为["US"].

PHONE_NUMBER_DISALLOWED_COUNTRIES

不允许使用电话号码的国家/地区代码列表。这可以与 结合使用PHONE_NUMBER_ALLOWED_COUNTRIES。

默认为[].

PHONE_NUMBER_CARRIER_LOOKUP

指示是否应通过 Twilio 执行运营商信息查找。（注意：运营商查询可能会影响计费。）

默认为True.

PHONE_NUMBER_ALLOWED_CARRIER_TYPES

允许的运营商类型列表。

可用类型：voip、landline和mobile。

默认为["mobile"].

OBFUSCATE

指示视图中显示的电话号码是否应该被混淆（(123) 456-7890vs (XXX) XXX-7890）。

默认为True.

ALLOW_REGISTER

指示是否应允许用户注册其电话号码（如果尚不存在）。

如果是这样False并且用户没有电话号码，他们将无法使用 2FA。

默认为True.

REGISTER_OPTIONAL

指示用户是否可以跳过用户注册。

如果True用户点击跳过按钮，用户将被重定向到REGISTER_OPTIONAL_URL.

默认为False.

REGISTER_OPTIONAL_URL

跳过注册时重定向用户的 URL。

默认为javascript:history.back().

RETRY_TIME

在最后一次交付尝试之后允许用户重新尝试交付验证的时间量（以秒为单位）。

Twilio 对重试之间的时间没有限制。

默认为 180 秒或 3 分钟。

VERIFY_SUCCESS_URL

成功验证后将用户重定向到的 URL。这不应返回 aResponse而不是（如HttpResponseRedirect），而应仅将 URL 作为字符串返回。

默认为reverse_lazy("twilio_2fa:success")

SERVICE_NAME

覆盖在 Twilio 控制台中设置的验证服务的友好名称。

可调用时发送的参数：

• user: 用户实例
• request:Request实例
• method: 方法字符串
• phone_number: 电话号码字符串

默认为None（无覆盖）。

ALLOW_CHANGE

指示用户是否可以更改与其 2FA 关联的电话号码。

默认为True.

MAX_ATTEMPTS

用户必须成功验证的最大尝试次数。

可调用时发送的参数：

• user: 用户实例

默认为5.

MAX_ATTEMPTS_TIMEOUT

在最大尝试失败后用户能够尝试另一次验证之前的时间量（以秒为单位）。

超时的用户将被重定向到失败视图。

如果此设置为None，0或False，则不会超时，用户将能够立即重试。

注意：此超时使用会话。建议将此逻辑放入中间件并将此值设置为 None。

默认为600秒或 10 分钟。

ALLOW_USER_ERROR_REDIRECT

当ALLOW_USER_CB返回时False，此设置返回将用户重定向到的 URL。

可调用时发送的参数：

• user: 用户实例

默认为/.

ALLOW_USER_ERROR_MESSAGE

ALLOW_USER_CB返回时，False此设置可以返回一条消息以通过 Django 消息添加。

可调用时发送的参数：

• user: 用户实例

默认为You cannot verify using 2FA at this time..

REGISTER_CB

此回调在用户注册他们的电话号码时触发，应用于更新用户。

发送到此回调的参数：

• user: 用户实例
• phone_number: 电话号码字符串

此回调预计不会返回。

PHONE_NUMBER_CB

此回调在每个验证请求上触发，并应返回用户的电话号码。

发送到此回调的参数：

• user: 用户实例

此回调的预期返回：

• 用户电话号码字符串

METHOD_DISPLAY_CB

此回调在每个请求上触发，并允许自定义方法图标和标签。

发送到此回调的参数：

• method: 方法字符串

此回调的预期返回是dict具有以下一个或多个值（如果不包括将使用默认值）：

• icon: Font Awesome 5 图标类（返回None不使用图标）
• label: 标签字符串

TIMEOUT_CB

此回调在每个验证请求上触发，并且应返回当前用户的超时时间戳作为DateTime实例，或者None如果不存在超时。

发送到此回调的参数：

• user: 用户实例

ALLOW_USER_CHANGE_CB

此回调在更改屏幕上触发，并应返回是否允许用户更改其电话号码。

发送到此回调的参数：

• user: 用户实例

IS_VERIFIED_CB

触发此回调以确定已通过身份验证的用户是否已通过 2FA 验证。

发送到此回调的参数：

• request: 请求实例

默认为False.

信号

信号名称带有前缀twilio_2fa_。

所有信号都至少带有以下参数：

• request: 当前Request实例
• user:User实例
• twofa：实例TwoFA

该类TwoFA具有以下属性：

• method: 用户选择的2FA验证方式
• phone_number：用于E164格式验证的电话号码
• twilio_sid：此验证实例的 SID
• attempts：尝试验证的次数

rate_limited

当对 Twilio 的请求受到速率限制时，将触发此信号。

随此信号发送的附加参数：

• exc:TwilioRestException实例

verification_start

此信号在验证开始时触发（GET调用/start）。应该用于清除任何验证会话。

verification_sent

每当发送验证时都会触发此信号。

随此信号发送的附加参数：

• timestamp:DateTime实例

verification_success

当用户成功完成验证时触发该信号。

在成功验证期间也会触发该verification_status_changed信号。

verification_status_changed

当 Twilio 验证状态改变时触发此信号。

status:approved和canceled的选项

随此信号发送的附加参数：

• status：状态验证更改为

verification_failed

当 Twilio 验证尝试失败时触发此信号。

verification_retries_exceeded

当验证失败的次数超过 时触发该信号MAX_ATTEMPTS。

您应该处理存储超时时间戳以供检索TIMEOUT_CB。

随此信号发送的附加参数：

• timeout： 的价值MAX_ATTEMPTS
• timeout_until:DateTime超时实例

定制

演示代码使用Bootstrap 5、Font Awesome 5和django-widget-tweaks。None 是绝对要求，可以使用自定义模板删除，或者在 Font Awesome 的情况下，定义METHOD_DISPLAY_CB设置。

所有模板都在twilio_2fa目录中。要覆盖这些模板，您可以将您的版本放在您自己的twilio_2fa目录中存储模板的任何位置。

_base.html

这是所有主模板扩展的主模板。

它为内容定义了一个块：（content上面以黄色概述）。对于django_widget_tweaks，该content块由 包裹WIDGET_ERROR_CLASS。

也可以使用header块更改标题（以红色标出）。标题图标类使用header_icon_class块更改（蓝色轮廓）和文本使用header_text块更改（绿色轮廓）。

_messages.html

此模板显示来自每个主模板的消息，django.contrib.messages并包含在每个主模板中。

_form_errors.html

此模板显示表单域的错误。field应该在上下文中传递。

failed.html

当用户的验证因验证超时、超过最大尝试次数、Twilio 的 API 失败或其他一般错误而失败时，将显示此模板。

它有条件地允许用户根据can_retry会话变量重试验证。

registration_form.html

此模板向用户显示注册表单，并用作 和 的基本register.html模板change.html。

register.html

此模板向用户显示注册表单。

如果ALLOW_REGISTRATION是False，则不会向用户显示此视图，并且如果没有返回电话号码，用户将被重定向到失败页面PHONE_NUMBER_CB。

它基于registration_form.html.

change.html

此模板向用户显示更改表单。

它基于registration_form.html.

start.html

该模板允许用户选择验证方法。

如果只存在一种方法，用户将看不到此页面。

success.html

VERIFY_SUCCESS_URL如果未设置，则此模板在成功验证时显示。

verify.html

此模板显示令牌表单。

发展

在根目录下执行以下步骤：

1. 创建一个虚拟环境并激活。
2. 安装django_twilio_2fa：pip install -e .

在目录中执行以下步骤test_app： 3. 在 requirements.txt 中更新此包的路径 4. 安装要求：pip install -r requirements.txt. 5. 复制.env-sample到.env并使用您的 twilio 设置进行更新。6. 运行迁移：python manage.py migrate. 7. 运行服务器：python manage.py runserver.

测试应用程序现在应该可以在http://localtest.me:8000获得。

去做

• 国际化
• 电子邮件验证
• WhatsApp 集成
• TOTP 集成
• 推动网络集成
• Web 流之外的 2FA 抽象

变更日志

• 0.23 - Twilio 速率限制错误处理
• 0.22 - 添加了国际化和电子邮件验证（感谢jgoodsell-summitgrp）