Django OTP WebAuthn

此包为Django提供了WebAuthn Passkeys的实现。它是一个多因素认证框架Django OTP的插件。在底层，此包使用py_webauthn来处理所有加密操作。

[!重要] 此软件包正在开发中，尚未经过充分测试和文档化。API 可能会发生变化。如果您对此软件包感兴趣，请给此仓库点星以显示您的兴趣。这有助于我优先考虑开发。如果您有兴趣贡献，请参阅 DEVELOPMENT.md 文件。

• Django OTP WebAuthn
  • 兼容性
    • 浏览器兼容性
  • 功能
  • 快速入门指南 - 如何在 Django 项目中使用 Passkeys
  • Passkeys究竟是什么？
    • Passkeys是如何工作的（简要说明）
    • 为什么使用 Passkeys？
    • 关于安全性的说明
  • 谁使用 Passkeys？
  • 进一步阅读
  • 开发
  • 许可证

兼容性

• Django >= 4.2
• Python >= 3.9
• django-otp >= 1.2.0

浏览器兼容性

Passkeys 支持大多数现代浏览器。以下是支持 Passkeys 的浏览器列表

• Chrome 67+
• Firefox 60+
• Safari 13+
• Microsoft Edge 18+

完整列表，请参阅 caniuse.com/webauthn。

功能

• Passkeys 作为第二因素。 用户在输入密码后，只需在浏览器提示中点击“是”即可验证其身份。
• 无密码登录 Passkeys（可选）。 用户可以使用生物识别传感器、安全密钥或其他兼容设备来验证其身份。如果只想将 Passkeys 作为第二因素使用，可以禁用此功能。
• 内置电池。 包含默认的前端 JavaScript 实现，可以直接使用，并为您简化复杂性。
• 灵活的前端。 您可以调整前端实现以适应您的品牌。或者如果您需要更定制的实现，可以自己实现前端。
• 与严格的 内容安全策略 (CSP) 兼容。 前端实现不依赖于内联脚本，与严格的 CSP 设置兼容。

快速入门指南 - 如何在 Django 项目中使用 Passkeys

要快速在您的 Django 项目中使用 Passkeys，请按照以下步骤操作

1. 从 PyPI 安装软件包

   pip install django-otp-webauthn
   

2. 将 django_otp_webauthn 添加到您的 Django 设置中的 INSTALLED_APPS

   INSTALLED_APPS = [
       ...
       "django_otp_webauthn",
       ...
   ]
   

3. 将所需的 URL 添加到您的 Django 项目

   # urls.py
   
   from django.urls import include, path
   
   urlpatterns = [
       ...
       path("webauthn/", include("django_otp_webauthn.urls", namespace="otp_webauthn")),
       ...
   ]
   

4. 将所需的设置添加到您的 Django 设置中。此示例假设您想配置为 localhost。您需要根据您的生产环境调整设置。

   # settings.py
   
   # The name of the relying party (RP). This is sometimes shown to the user when they register a Passkey.
   OTP_WEBAUTHN_RP_NAME = "My Website Inc."
   # This is necessary to bind the Passkey to a specific domain. This should be the domain of your website.
   OTP_WEBAUTHN_RP_ID = "your-domain.com"
   # This is used to check the origin of the request and is used for security. It is similar to Django's CSRF_TRUSTED_ORIGINS setting.
   # The origins must always be a subdomain of the RP ID or the RP ID itself.
   OTP_WEBAUTHN_ALLOWED_ORIGINS = ["https://your-domain.com", "https://subdomain.your-domain.com"]
   

5. 将 django_otp_webauthn.backends.WebAuthnBackend 添加到您的 Django 设置中的 AUTHENTICATION_BACKENDS。此步骤是使“无密码身份验证”工作所必需的。

如果您仅使用 Passkeys 作为二级验证步骤，则无需添加此后端。

```python
AUTHENTICATION_BACKENDS = [
    ...
    "django_otp_webauthn.backends.WebAuthnBackend",
    ...
]
```

6. 将注册代码添加到您的登录用户模板。

   <!-- logged_in_template.html -->
   {% load otp_webauthn %}
   
   {% comment %}
   This template is displayed when WebAuthn registration is supported.
   The template must contain a button with the id `passkey-register-button`. To display status and error messages, include an element with the id `passkey-register-status-message`.
   {% endcomment %}
   <template id="passkey-registration-available-template">
       <div>
           <button type="button" id="passkey-register-button">Register Passkey</button>
           <div id="passkey-register-status-message"></div>
       </div>
   </template>
   
   {% comment %}
   This template is displayed when WebAuthn registration is not supported.
   {% endcomment %}
   <template id="passkey-registration-unavailable-template">
       <p>Sorry, your browser has no Passkey support</p>
   </template>
   
   {% comment %}
   This placeholder element will be replaced with either the contents of the `passkey-registration-available-template` or the `passkey-registration-unavailable-template` template.
   {% endcomment %}
   <span id="passkey-registration-placeholder"></span>
   
   {% comment %}
   This template tag renders all the necessary <script> tags for the default registration implementation
   {% endcomment %}
   {% render_otp_webauthn_register_scripts %}
   

7. 在您的登录页面上包含以下内容以启用无密码登录

   {% load otp_webauthn %}
   
   <form method="post">
       {# Suppose there is an username field on your page that has CSS selector: input[name="username"] #}
       <label for="id_username">Username</label>
       <input id="id_username" type="text" name="username" autocomplete="username">
       {# Other fields omitted for brevity #}
   
       {# This placeholder element will be replaced with either the contents of the `passkey-verification-available-template` or the `passkey-verification-unavailable-template` template. #}
       <span id="passkey-verification-placeholder"></span>
   
       {% comment %}
       This template is displayed when WebAuthn authentication is supported. Typically, you would want to display a button that the user can click to authenticate using a Passkey.
       The template must contain a button with the id `passkey-verification-button`. To display status and error messages, include an element with the id `passkey-verification-status-message`.
       {% endcomment %}
       <template id="passkey-verification-available-template">
           <button type="button" id="passkey-verification-button">Login using a Passkey</button>
           <div id="passkey-verification-status-message"></div>
       </template>
   
   
       {% comment %}
       This template is displayed when WebAuthn is not supported.
       {% endcomment %}
       <template id="passkey-verification-unavailable-template">
           <p>Sorry, your browser has no Passkey support</p>
       </template>
   
       {% comment %}
       This template tag renders all the necessary <script> tags for the default verification implementation
   
       To make browsers automatically suggest a Passkey when you focus the username
       field, make sure `username_field_selector` is a valid CSS selector.
       {% endcomment %}
       {% render_otp_webauthn_auth_scripts username_field_selector="input[name='username'] %}
   </form>
   

8. 不要忘记运行迁移

   python manage.py migrate
   

9. 就是这样！您现在应该在您的登录用户模板上看到“注册 Passkey”按钮。点击此按钮将启动注册过程。注册后，您应该在您的登录页面上看到“使用 Passkey 登录”按钮。点击此按钮将提示您使用 Passkey 进行身份验证。或者如果您的浏览器支持，您将在焦点在用户名字段时被提示使用 Passkey。

Passkeys究竟是什么？

Passkeys 是一种新的网络身份验证方式。官方上它们被称为“WebAuthn 证书”，但 Passkeys 是一个更易记忆、人性化的名称，已被选中来描述它们。它们允许您的网站用户使用他们的手机、笔记本电脑、安全密钥或其他兼容设备进行身份验证，而无需记住密码。

Passkeys 遵循 WebAuthn 标准。该标准描述了一种使用 公钥密码学 来验证用户的方法。

Passkeys是如何工作的（简要说明）

以下是对 Passkey 工作原理的（过于简化的）解释。如需更详细的解释，请尝试访问Auth0 的交互式 WebAuthn 演示。它对 WebAuthn 流程有非常精彩的解释！或者深入了解WebAuthn 标准本身。

1. 已经认证的用户将 Passkey 注册到您的网站上。在用户的设备上生成一个公钥-私钥对。私钥安全存储，公钥发送到服务器并与认证用户关联。服务器上还存储了额外的一项信息，称为“凭证 ID”。
2. 当用户想要进行认证时，服务器向用户的设备发送一个挑战。用户的设备使用私钥对挑战进行签名，并将签名连同凭证 ID 一起发送回服务器。
3. 服务器查找与给定凭证 ID 关联的公钥，并使用它来检查签名。这个签名是由我们文件中的公钥对应的私钥生成的吗？如果是，那么用户一定拥有私钥，并且已通过认证。

为什么使用 Passkeys？

• 安全性。与密码相比，Passkey 对钓鱼攻击、凭证填充和其他常见攻击具有抵抗力。
• 便捷性。Passkey 比密码更方便。用户不必选择和记住密码，他们可以使用手机、笔记本电脑或安全密钥进行认证。与其他传统多因素认证方式相比，无需等待短信验证码到来或从认证器应用程序复制代码。只需在浏览器提示中点击“是”即可。

关于安全性的说明

Passkey 有时被誉为安全的银弹。虽然它们比密码更安全，但它们并不完美。

您需要信任用户的设备和其制造商。大多数设备支持在设备之间同步 Passkey，例如通过 iCloud 或 Google 账户。这意味着如果有人获取了用户的 iCloud 或 Google 账户访问权限，他们可能会访问其 Passkey。那些账户和设备安全保护不佳的用户处于风险之中。然而，这并非 Passkey 所独有。同样风险存在于支持设备同步的密码管理器和其他多因素认证方式。Passkey 通过其抵抗钓鱼攻击、凭证填充和便捷性等优势优于其他方法。

作者认为 Passkey 的好处大于风险。本节仅供您参考。

谁使用 Passkeys？

许多网站已经支持 Passkey。以下是一些知名示例

• GitHub
• Google
• Microsoft
• WhatsApp

是时候让您的网站也支持 Passkey 了！

进一步阅读

以下是一些关于 Passkey 的学习资源

• Passkeys.dev - 有关 Passkey 的基本信息
• Auth0 的 WebAuthn 演示 - 对 WebAuthn 流程有非常精彩的解释！
• WebAuthn 标准（工作草案）

开发

有关如何开发和为该项目做出贡献的信息，请参阅DEVELOPMENT.md。

许可证

本项目采用 BSD 3-Clause 许可协议。有关详细信息，请参阅LICENSE文件。