如何验证你的 tsidp 部署是否正确?用官方 verifier 工具跑通 8 步 OIDC 流程
如何验证你的 tsidp 部署是否正确?用官方 verifier 工具跑通 8 步 OIDC 流程
tsidp 是一个面向 Tailscale 网络(tailnet)的开源 OIDC / OAuth 身份提供商(IdP),让你用 Tailscale 账号为任何支持 OpenID Connect 的应用登录。部署完成后,最让人担心的问题是:"它到底配对了没有?" 好消息是,仓库自带一个官方 verifier 验证工具,位于 cmd/verifier/README.md,只需一条命令,就能自动跑通完整的 8 步 OIDC 授权码流程,并把 ID Token、Introspection、UserInfo 的结果全部打印出来,是验证 tsidp 部署是否正确的最快方法。
一、verifier 工具是什么?
verifier 是一个用 Go 编写的"一次性 OIDC 客户端",源码见 cmd/verifier/verifier.go。它会像真实应用一样依次访问你的 tsidp 实例:拉取元数据 → 注册客户端 → 请求授权 → 换取令牌 → 校验签名 → 查询令牌信息,最后输出 OIDC FLOW COMPLETE 表示一切正常。
与手工用 curl 测试相比,它有三个明显优势:
- 全流程自动化:自动处理 state、nonce、PKCE(RFC 7636)等参数,省去手动拼接 URL 的繁琐;
- 签名真校验:会从
/.well-known/jwks.json拉取公钥,用 RSA/SHA-256 验证 ID Token 签名,而不是只看"有返回"; - 可选项覆盖 STS:加上
-sts参数还能验证 RFC 8693 令牌交换(token exchange)是否可用。
二、验证前只需完成 2 项准备
1. 确保 tsidp 已在 tailnet 中运行
使用 Docker 部署时(推荐),Dockerfile 对应的镜像可通过 docker compose up -d 启动。首次启动后,在浏览器访问 https://idp.yourtailnet.ts.net,可能要点几分钟——tsidp 首次启动需要时间生成 TLS 证书,证书没就绪时元数据请求会失败,这是最常见的"假故障"。
2. 配置应用权限(Application Capability Grant)
tsidp 默认拒绝访问管理 UI 和动态客户端注册(DCR)端点。请在 Tailscale 管理控制台的 Access controls 中为 tailscale.com/cap/tsidp 配置 grant,开启 allow_admin_ui、allow_dcr,如需验证 STS 还要填写 users / resources,示例见 README.md 中的 "Setting an Application Capability Grant" 一节(实现逻辑在 server/appcap.go)。
三、一键运行:3 条命令启动验证
克隆仓库并进入 verifier 目录:
git clone https://gitcode.com/gh_mirrors/tsi/tsidp
cd tsidp/cmd/verifier
go run . -sts -idp https://idp.yourtailnet.ts.net
参数说明:
| 参数 | 作用 |
|---|---|
-idp |
必填,你的 tsidp Issuer URL(即 https://idp.yourtailnet.ts.net) |
-sts |
可选,额外验证 STS 令牌交换(需服务端启用 -enable-sts / 环境变量 TSIDP_ENABLE_STS=1) |
-client_id / -client_secret |
可选,提供固定客户端凭据;不提供则自动走动态注册 |
⚠️ 第 3 步需要你在浏览器里登录一次:verifier 会打印一个授权 URL,打开它并用 Tailscale 账号登录后,浏览器会跳转到
http://127.0.0.1:8080/auth/callback并显示"无法访问"——这是正常现象(本地并没有监听 8080 端口)。把地址栏里完整的 URL 复制粘贴回终端即可,verifier 会自动从里面提取授权码。
四、8 步 OIDC 流程详解:每一步验证什么
下面是 verifier 内部依次执行的 8 个步骤,以及"成功"长什么样:
| 步骤 | 动作 | 成功标志 |
|---|---|---|
| 1 | 拉取 /.well-known/openid-configuration 提供商元数据(实现见 server/oauth-metadata.go) |
✅ Authorization Endpoint: .../authorize |
| 2 | 动态客户端注册(DCR),自动创建临时客户端 | ✅ Registered Client ID: ... |
| 3 | 生成带 state、nonce、PKCE 的授权 URL 并请求 | ✅ Provider sent a redirect |
| 4 | 解析你粘贴的回跳 URL,比对 state,提取授权码 | ✅ Received authorization code: ... |
| 5 | 用授权码换取令牌,并手动验证 ID Token 签名与全部 claims(iss / aud / exp / nonce) | ✅ Signature is valid. All claims are valid. |
| 6 | 调用 introspection 端点(RFC 7662)检查 Access Token 状态 | ✅ Introspection response received |
| 7 | 携带 Bearer 令牌调用 userinfo 端点 | ✅ UserInfo response received |
| 8 | STS 令牌交换(RFC 8693,仅 -sts 时执行) |
✅ Received exchanged token: ... |
全部通过后,终端会打印 OIDC FLOW COMPLETE 和完整的 ID Token Claims、Introspection Response、UserInfo Response,可直接留档作为验收记录。输出示例可参考 cmd/verifier/README.md 的 "Output Example" 部分。
五、验证失败?对照这张表排查
| 失败步骤 | 常见原因 | 解决办法 |
|---|---|---|
| Step 1 元数据拉取失败 | 首次启动 TLS 证书未生成;Issuer URL 拼错 | 等待几分钟后重试;确认 URL 与 -hostname 一致 |
| Step 2 动态注册失败 | 未配置 app capability grant | 开启 allow_dcr;或改用 -client_id / -client_secret 静态凭据(管理界面见下图) |
| Step 4 state 不匹配 | 粘贴的回跳 URL 不完整 | 复制浏览器地址栏完整 URL,不要截断 |
| Step 5 签名验证失败 | JWKS 公钥获取异常或密钥变更 | 检查 /.well-known/jwks.json 是否可访问 |
| Step 8 STS 失败 | 服务端未启用令牌交换 | 启动时加 -enable-sts(Docker 中设 TSIDP_ENABLE_STS=1),并在 grant 中配置 users / resources |
六、验证通过后:把一个真实应用接上
verifier 全部 ✅ 之后,你的 tsidp 已经具备服务真实应用的能力。以 Proxmox 为例(完整图文见 docs/proxmox/README.md):在 Datacenter → Realms → Add → OpenID Connect Server 中,将 Issuer URL 指向你的 https://idp.yourtailnet.ts.net:
保存后,用 Tailscale 身份登录 Proxmox,即完成端到端闭环:
💡 其他支持自定义 OIDC 提供方的应用(Grafana、Jellyfin 等)配置方式相同:填入 Issuer URL + Client ID/Secret 即可。
七、相关源码与文档速查
- 验证工具:cmd/verifier/verifier.go、cmd/verifier/README.md
- 授权与令牌端点:server/authorize.go、server/token.go
- 用户信息端点:server/userinfo.go
- 客户端管理(DCR):server/clients.go
- 元数据端点:server/oauth-metadata.go
- 管理 UI:server/ui.go
- 服务端入口:tsidp-server.go,构建脚本:Makefile
小结:记住核心动作——go run . -sts -idp https://idp.yourtailnet.ts.net,浏览器里登录一次、粘贴一次回跳 URL,看到 OIDC FLOW COMPLETE 就可以放心地把 tsidp 接入你的应用了。



