如何验证你的 tsidp 部署是否正确?用官方 verifier 工具跑通 8 步 OIDC 流程

原创2026-11-01 14:46:021,941 阅读

如何验证你的 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 流程详解:每一步验证什么

tsidp OIDC 授权流程验证成功后在 OAuth 认证面板中获取到 Access Token 的界面截图

下面是 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

tsidp 管理界面 OIDC Clients 列表页面,用于验证 DCR 动态注册是否成功

六、验证通过后:把一个真实应用接上

verifier 全部 ✅ 之后,你的 tsidp 已经具备服务真实应用的能力。以 Proxmox 为例(完整图文见 docs/proxmox/README.md):在 Datacenter → Realms → Add → OpenID Connect Server 中,将 Issuer URL 指向你的 https://idp.yourtailnet.ts.net:

Proxmox 中添加 OpenID Connect Server 的对话框,Issuer URL 指向 tsidp 部署地址用于部署验证

保存后,用 Tailscale 身份登录 Proxmox,即完成端到端闭环:

使用 tsidp 提供的 Tailscale realm 登录 Proxmox 的界面,验证 tsidp OIDC 部署生效

💡 其他支持自定义 OIDC 提供方的应用(Grafana、Jellyfin 等)配置方式相同:填入 Issuer URL + Client ID/Secret 即可。

七、相关源码与文档速查

小结:记住核心动作——go run . -sts -idp https://idp.yourtailnet.ts.net,浏览器里登录一次、粘贴一次回跳 URL,看到 OIDC FLOW COMPLETE 就可以放心地把 tsidp 接入你的应用了。

登录后查看全文
tsidp