# 双因子验证

hsweb提供了双因子验证功能,默认提供了totp实现,可通过totp app(比如:[Google Authenticator](https://github.com/google/google-authenticator))进行验证码获取。可以通过拓展实现接口短信验证等功能。

### 开启双因子验证

配置 application.yml

```
hsweb:
    authorize:
        two-factor:
            enable: true
        totp:
          enable: true # 开启totp支持
          domain: hsweb.me
```

在需要验证的接口上注解:

```java
@PostMapping
@TwoFactor("update-password") //调用此接口时,需要进行双因子验证
public ResponseMessage<Boolean> updatePassword(String password){
    //业务逻辑
}
```

### TOTP

如果开启了TOTP 双因子验证,在创建用户时会生成用户的totp验证密钥,并发出事件:`TotpTwoFactorCreatedEvent` ，通过监听此事件进行自定义处理：比如发送邮件通知等。

### 验证流程

1. 调用接口,判断当前是否已经验证通过
2. 如果没有验证通过,返回{"status":403,"code":"need\_tow\_factor","message":"需要进行双因子验证","provider":"totp"}
3. 客户端根据返回码,引导用户输入验证码
4. 将验证码添加到第一步的接口参数中,默认参数名为: `verifyCode`
5. 验证通过后,在`@TwoFactor(timeout=600000L)`毫秒内再次调用无需重复输入,默认为`10分钟`.

### 自定义验证策略

hsweb默认只提供了TOTP方式的验证实现,，但是提供了拓展方式可以自定义验证策略，比如：短信验证

1. 继承抽象类: `DefaultTwoFactorValidatorProvider`并重写对应方法
2. 修改配置: `hsweb.authorize.two-factor.default-provider=自定义的provider`，或者在注解中指定provider: `@TwoFactor(value="验证接口标识",provider="自定义的provider")`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hsweb.io/framework/quan-xian-kong-zhi/shuang-yin-zi-yan-zheng.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.