Wicket 是什么
Wicket（模块路径 github.com/gonewx/wicket）是一个 OpenID Connect / OAuth 2.0 授权服务器库。它不是独立部署的认证服务，而是一组 http.Handler 中间件：你把它挂进自己的 Go 服务里，这个服务就能对外提供 /connect/token、/connect/authorize、/.well-known/openid-configuration 等标准协议端点。
go
// 宿主应用的 handler 链：wicket 处理协议端点，其余请求原样交给 app
handler := hosting.ScopeMiddleware(root)(srv.UseWicket()(app))
http.ListenAndServe(":5000", handler)完整可运行的装配见 快速开始。
定位：嵌入式中间件
Wicket 运行在你的进程里，和你的业务代码共享同一个 HTTP 监听、同一套部署流水线：
- 协议由 wicket 负责：请求解析与校验、客户端认证、令牌签发与校验、发现文档、JWKS 发布。
- 用户与页面由宿主负责：用户库、密码校验、登录页、同意页、错误页都由你的应用实现。wicket 只在需要用户交互时把浏览器重定向到你配置的 URL。
- 基础设施由宿主注入：数据库、签名密钥、日志、清理调度都由宿主提供。wicket 主模块不依赖任何数据库驱动，也不在后台自起 goroutine。
能做什么
| 能力 | 说明 |
|---|---|
| 协议端点 | 授权、授权回调、令牌、发现文档、JWKS、UserInfo、内省、结束会话（含回调）、会话检查 iframe、CIBA 后端通道认证 |
| 授权类型 | authorization_code（默认要求 PKCE）、client_credentials、refresh_token、urn:openid:params:grant-type:ciba、urn:ietf:params:oauth:grant-type:device_code（仅令牌端点，见下）、password（默认拒绝，需注入校验器） |
| 令牌形态 | JWT 访问令牌（typ 为 at+jwt）、身份令牌、刷新令牌；引用令牌的模型与存储端口已定义，但 v0.1.4 签发路径尚未接通 |
| 外部登录 | 内置 Google、Facebook 认证处理器；JWT Bearer 认证；运行时动态认证方案 |
| 无状态验签 | oidcverify（本地验证外部 OIDC 提供者签发的 ID Token）、wechatverify（微信服务端交换）、phoneverify（阿里云号码认证）三个独立包，不依赖任何存储 |
| 存储 | 三族存储端口（storage / session / keymgmt）+ 契约测试套件；内存实现仅供开发；官方 PostgreSQL 适配器 github.com/gonewx/wicket-pg |
| 签名密钥 | 宿主手动提供签名凭据，或使用 keymgmt 包的自动轮换管理器 |
不做什么
- 不提供用户管理与登录 UI。 没有用户表、注册、找回密码、登录页模板。这些属于宿主应用。
- 不内置交互式登录的 cookie 认证处理器。 用户登录后由宿主写入的认证 cookie（方案名
wicket），其 handler 需宿主通过ServerConfig.SetAuthenticationHandlerProvider提供，见 核心概念。 - 不实现以下端点（v0.1.4）：令牌吊销
/connect/revocation、设备授权/connect/deviceauthorization、mTLS 端点。它们只有路径常量，没有注册处理器——请求会透传给宿主 handler。注意发现文档在默认配置下仍会公布revocation_endpoint与device_authorization_endpoint，见 配置选项 的端点开关一节。 - 不处理 CORS 响应头和反向代理头。 见 CORS 跨域 与 生产部署清单。
- 不自起后台任务。 过期数据清理由宿主按自己的调度驱动。
适用场景
适合：
- 你已经有一个 Go 后端，希望由它自己向移动端、单页应用、第三方客户端或内部服务签发 OAuth 2.0 / OIDC 令牌，而不是再运维一个独立的认证服务。
- 机器对机器调用（
client_credentials），需要标准的访问令牌与内省端点。 - 需要把“Apple / Google / 微信 / 手机号”等外部凭据换成你自己的本地身份——这部分可以只用无状态验签包，完全不装配授权服务器。
不太适合：
- 需要开箱即用的管理后台、用户自助门户、多租户控制台。
- 需要成熟的 SAML、WS-Federation 等其他协议。
- 对“生产就绪”的要求高于一个 v0.1.x 早期版本能给的承诺（见下）。
与独立部署的认证服务对比
| 维度 | 嵌入 wicket | 独立部署的认证服务 |
|---|---|---|
| 部署与运维 | 随宿主进程发布，无额外服务 | 单独的服务、数据库、升级节奏 |
| 用户数据访问 | 直接调用宿主的用户库与业务逻辑 | 通过 API、同步或联邦方式对接 |
| 登录页定制 | 完全由宿主实现，零限制 | 受产品的主题/模板机制约束 |
| 开箱功能 | 只有协议核心，周边需自建 | 通常自带管理界面、用户管理、审计 |
| 故障隔离 | 与宿主同进程，宿主故障即认证故障 | 认证服务独立伸缩、独立故障域 |
| 安全责任 | 密钥、存储、HTTPS、日志由宿主负责 | 大部分由服务提供方承担 |
简单说：wicket 用“更多由你掌控”换取“更少的运维面”。如果你的团队愿意承担装配与运维责任，它能让认证能力与业务代码贴得最近。
当前状态
- 最新版本 v0.1.4，属于 早期版本。v0.x 期间 API 可能出现不兼容变更，请在
go.mod中固定精确版本。 - 需要 Go 1.27 工具链。
- 根包的 Go 包名是
gois（与目录名不同），示例中统一用别名导入：wicket "github.com/gonewx/wicket"。 - 部分能力仍有已知缺口，本文档会在对应页面明确标注，例如：