术语与参考资料
术语速查
| 术语 | 含义 | 本项目对应物 |
|---|---|---|
| OP（OpenID Provider） | 授权服务器，负责认证用户 + 签发令牌 | Yagang.Identity.Api（7016） |
| RP / Client | 依赖方（要登录的应用） | demo 客户端（5173） |
| end-session | OAuth 的"登出"端点（OIDC 里叫 RP-Initiated Logout） | GET/POST /connect/logout |
| PKCE | 公开客户端的"证明我就是发起人"机制：code_verifier / code_challenge | 客户端 Requirements.Features.ProofKeyForCodeExchange 强制 |
| consent | 用户同意把哪些 scope 授权给哪个客户端 | React 同意页 + oi_ath 永久授权 |
| permanent authorization | 一次同意后写入的持久授权记录 | oi_authorizations 表 |
| passthrough | 让 MVC 控制器处理 OpenIddict 端点（而不是框架自己处理） | EnableAuthorizationEndpointPassthrough() 等 |
| forwarded scheme | OpenIddict Client 为每个外部提供方注册的认证 scheme | 名为 GitHub 的 scheme |
| external cookie | Identity 在"外部回调和最终登录之间"用的中间 cookie（5 分钟） | 本项目同款：/callback/login/github 写入 → /Account/ExternalLoginCallback 消费（换应用 cookie 或转确认页） |
| 应用 cookie（application cookie） | Identity 的用户会话 cookie | .AspNetCore.Identity.Application（默认名） |
| 渐进增强（progressive enhancement） | 先用浏览器原生行为保证"能用"，再用 JS 补体验（本例：原生 form 提交 + onSubmit 切 loading） | 登录 / 同意 / 登出 / 外部账号确认四页（见表单登录与 loading） |
关键常量（本项目）
| 项 | 值 |
|---|---|
| OP 地址 | https://localhost:7016 |
| 登录/同意/登出/外部账号确认页 | https://localhost:7016/Account/Login、/Account/Consent、/Account/Logout、/Account/ExternalLoginConfirm |
| 客户端 id / 回调 | client-demo / http://localhost:5173/signin-callback |
| 演示用户 | alice / P@ssw0rd-001!（角色 admin） |
| scope | openid、offline_access、demo_api、email、profile、roles |
| 外部登录回调 | https://localhost:7016/callback/login/github |
参考实现与资料
| 参考 | 位置 | 说明 |
|---|---|---|
| openiddict-core 源码 | reference/openiddict-core/ | 判断框架行为以它为准（如 OpenIddictServerHandlers.cs） |
| openiddict-documentation | reference/openiddict-documentation/ | 官方文档源码 |
| 本项目 AI 交接记忆 | backend/Yagang.Identity/AGENTS.md | 含更长的历史踩坑记录与决策过程 |
| 本项目 README | backend/Yagang.Identity/README.md | 启动与测试清单 |
| OpenIddict 错误码 | https://documentation.openiddict.com/errors | 例如 ID2015、ID2043、ID2052、ID2054 |
| Identity 默认 UI 登录页源码 | dotnet/aspnetcore → src/Identity/UI/src/Areas/Identity/Pages/V5/Account/Login.cshtml | 业界"真表单"登录的参照物：<form id="account" method="post"> + autocomplete + ModelState 回显 |
| HTML 规范：构造表单数据集合 | https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#constructing-form-data-set | 解释"disabled 控件不参与提交""只有被点的提交按钮带 name/value" |
| antd Button / Spin | https://ant.design/components/button · https://ant.design/components/spin | loading（不加 disabled、拦后续点击）与 fullscreen 的行为 |
学习路径（如果只看一页）
- 流程总览 —— 建立整体地图；
- ③ 同意流程 —— 最能体现"授权服务器在做什么"的一段代码；
- Program.cs —— 所有零件如何装配；
- 坑速查 —— 排错清单；
- 学完之后：下一步学什么 —— 官方 16 个示例的对照表、推荐阅读顺序、生产化清单、自测问题。
这个文档站怎么部署
- 源文件：本仓库
docs/（VitePress）； - 构建：
pnpm docs:build（在docs/目录）； - 部署：GitHub Actions（
.github/workflows/deploy-site.yml）在main分支推送且docs/**变更时构建并发布到 GitHub Pages； - 线上地址：https://chenyagang333.github.io/yagang-identity/。
bash
# 本地预览
cd docs
pnpm install
pnpm docs:dev # http://localhost:5173/yagang-identity/
pnpm docs:build # 产物在 docs/.vitepress/dist
pnpm docs:preview