> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/security/captcha.md).

# 验证码与确认令牌

使用 Authencode 图片挑战和短期确认令牌，理解两阶段核验、缓存及重放边界。

Authencode 使用图片挑战降低自动化滥用。它先验证答案，再签发一个供后续业务流程消费的短期确认令牌。因此，显示图片、提交答案和消费确认是三个步骤，不应把挑战令牌直接当成已经验证的结果。

## 前置条件

部署 Zongsoft.Security.Captcha 及主 Security 插件，HTTP 场景还需要 Security.Web。宿主应提供框架的分布式缓存契约；多实例必须使用共享缓存，否则不同节点可能找不到同一挑战。

{% code title="Captcha.deploy（追加片段）" %}

```ini
[plugins zongsoft security captcha]
nuget:Zongsoft.Security.Captcha
```

{% endcode %}

## 客户端流程

1. 通过已部署的验证码端点请求 Authencode 方案。
2. 显示返回的 PNG，并从 `X-Captcha` 响应头保留挑战令牌。
3. 将用户答案与挑战令牌组成 `token:code` 提交，提供者也接受 `token=code`。
4. 保存验证成功后返回的确认令牌，将它交给要求验证码的业务流程。
5. 业务最终核验确认令牌，消费对应的确认缓存项并删除原挑战。

浏览器跨域使用时还要确认响应头可被前端读取；反向代理不能丢弃 `X-Captcha`。图片渲染失败时检查目标环境字体和图像依赖。

## 有效期与一次性语义

当前实现的挑战有效期为 10 分钟，确认令牌有效期为 5 分钟。最终核验通过缓存的移除并取值操作消费确认项，同一个确认令牌不能再次成功使用。

{% hint style="warning" %}
🚨 答案验证成功本身不会立即删除挑战。最终消费前，同一挑战可以产生多个确认令牌，因此不能把整个挑战流程描述为严格单次使用。业务还需要自己的请求限速和操作幂等规则。
{% endhint %}

## 集成时应验证什么

分别测试错误答案、挑战过期、确认过期、重复确认和跨节点确认。只调用图片生成器得到一张 PNG，并没有验证缓存、令牌与业务确认流程。

验证码用于防滥用，不证明用户身份。需要提供适合无法完成图片挑战用户的替代流程，也不要把答案或令牌写入日志。

实现依据：[AuthencodeCaptcha](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Security/captcha/AuthencodeCaptcha.cs)、[验证码控制器](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Security/api/Controllers/CaptchaController.cs)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/security/captcha.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.