注意：本帖的内容为未来展望，尚未在HA0.76.2中添加。
多因素认证模块(Multi-factor Authentication Modules)
多因素认证（MFA）模块用来与认证模型(Authentication Providers)结合使用，以提供完整可配置的身份验证框架。每个MFA模块可以提供一个多因素认证功能。用户可以启用多个MFA模块，但只能在登录过程中选择1个模块。
Multi-factor Authentication Modules are used in conjunction with Authentication Provider to provide a fully configurable authentication framework. Each MFA module may provide one multi-factor authentication function. User can enable mulitple mfa module, but can only select one module in login process.
定义1个MFA模块(Defining an mfa auth module)
我们目前仅支持内置的MFA模块。将来可能会支持自定义的验证模块。
We currently only support built-in mfa auth modules. Support for custom auth modules might arrive in the future.
MFA模块定义于homeassistant/auth/mfa_modules/<name of module>.py。该模块需要提供1个MultiFactorAuthModule(多因素认证模块)类的实现。
Multi-facor Auth modules are defined in homeassistant/auth/mfa_modules/<name of module>.py. The auth module will need to provide an implementation of the MultiFactorAuthModule class.
完整的MFA模块的示例，请参阅insecure_example.py。
For an example of a fully implemented auth module, please see insecure_example.py.
MFA模块应扩展以下MultiFactorAuthModule类方法。
Multi-factor Auth modules shall extend the following methods of MultiFactorAuthModule class.
| 方法(method) |
必选(Required) |
描述(Description) |
@property def input_schema(self) |
是 |
返回用来定义用户输入表单的纲要。 |
async def async_setup_flow(self, user_id) |
是 |
返回配置流程来处理安装工作流程。 |
async def async_setup_user(self, user_id, setup_data) |
是 |
设置使用此MFA模块的用户。 |
async def async_depose_user(self, user_id) |
是 |
移除使用此MFA模块的用户。 |
async def async_is_user_setup(self, user_id) |
是 |
返回用户是否已配置该MFA模块。 |
async def async_validation(self, user_id, user_input) |
是 |
传入用户id和用户输入, 返回验证结果. |
配置流程(Setup Flow)
在用户可以使用MFA模块之前，必须启用或设置它。所有可用模块都将列在用户配置文件页面中，用户可以启用自己想要使用的模块。设置数据输入流程将指导用户完成必要的步骤。
Before user can use a multi-factor auth module, it has to be enabled or set up. All availiable modules will be listed in user profile page, user can enable the module he/she wants to use. A setup data entry flow will guide user finish the neccessary steps.
每个MFA模块都需要实现一个从mfa_modules.SetupFlow继承的设置流程处理程序（如果只要简单的设置步骤，SetupFlow也可以使用）。例如，对于Google身份验证器（TOTP，基于时间的一次性密码）模块，流程必须为：
- 生成一个秘钥并将其存储在配置流程的实例上
- 以描述中（通过
description_placeholders以base64注入 ）的QR码返回async_show_form
- 用户扫描代码并输入代码以验证其是否正确扫描并同步
- TOTP模块保存了秘钥及用户id，并为该用户启用模块
Each MFA module need to implement a setup flow handler extends from mfa_modules.SetupFlow (if only one simple setup step need, SetupFlow can be used as well). For example for Google Authenticator (TOTP, Time-based One Time Password) module, the flow will need to be:
- Generate a secret and store it on instance of setup flow
- Return
async_show_form with a QR code in the description (injected as base64 via description_placeholders)
- User scans code and enters a code to verify it scanned correctly and clock in synced
- TOTP module saved the secret along with user_id, module is enabled for user
工作流程(Workflow)
未完成的工作：绘制图表
TODO: draw a diagram
用户
== 选择认证模型
==> 登录流程初始化
== 输入/验证 用户名/密码
==> 登录流程结束
==> 如果用户开启MFA模块
==> 登录流程选择MFA模块
==> 登录流程MFA
== 输入/验证 MFA代码
==> 登录流程结束
==>完成
User == select auth provider ==> LoginFlow.init == input/validate username/password ==> LoginFlow.finish ==> if user enabled mfa ==> LoginFlow.select_mfa_module ==> LoginFlow.mfa == input/validate MFA code ==> LoginFlow.finish ==> Done
配置示例(Configuration example)
# configuration.xml
homeassistant:
auth_providers:
- type: homeassistant
- type: legacy_api_password
auth_mfa_modules:
- type: totp
- type: insecure_example
users: [{'user_id': 'a_32_bytes_length_user_id', 'pin': '123456'}]
auth:
在这个例子中，用户将首先从登录表单中选择homeassistant或legacy_api_password这两种认证模型。对于homeassistant认证模型，用户首先会输入用户名/密码，如果用户同时启用了totp和insecure_example这2个MFA模块，则用户需要选择1个MFA模块，然后输入谷歌身份验证码或输入选定的PIN码。
In this example, user will first select from homeassistant or legacy_api_password auth provider. For homeassistant auth provider, user will first input username/password, if that user enabled both totp and insecure_example, then user need select one auth module, then input Google Authenticator code or input pin code base on the selection.
insecure_example仅用于演示目的，请不要在生产中使用它。
insecure_example is only for demo purpose, please do not use it in production.
验证会话(Validation session)
不像认证模型，MFA模块使用会话来管理验证。认证模型验证后，MFA模块将创建验证会话，包括实验时间和来自认证模型验证结果的用户id。MFA模块不仅会确认用户的输入，还会确认会话是否过期。该验证会话的数据存储在登录流程实例中。
Not like auth provider, auth module use session to manage the validation. After auth provider validated, mfa module will create a validation session, include an experiation time and user_id from auth provider validate result. Mutli-factor auth moudle will not only verify the user input, and also verify the session is not experied. The validatoin session data storges in login flow instance.
发表于 2018-8-26 01:14:17
发表于 2018-8-26 01:44:25
楼主