跳到主要内容

企业自建设备码授权服务对接 CloudBase CLI

本文说明企业如何使用 CloudBase CLI 与自建授权服务完成具体对接，并基于参考实现落地整套流程。

如果你想先了解设备码授权的背景和协议约定，请先阅读 设备码授权概览。

自建授权服务参考实现仓库：cloudbase-cli-auth-endpoint

1. CloudBase CLI 如何配合这套流程​

1.1 配置授权服务地址​

企业接入这套流程时，先把授权服务地址写入 CLI 配置。例如：

tcb config set customOAuthEndpoint https://auth.example.com/auth

其中 https://auth.example.com/auth 需要替换为您自行配置的授权服务路径。

然后再执行：

tcb login

这样做的原因是：

  1. 首次登录时，CLI 会用这个地址发起设备码授权。
  2. 登录成功后，如果本地保存了 refreshToken，CLI 续期时还需要知道同一个授权服务地址。
  3. 用户执行 tcb logout 时，CLI 也需要回到这个地址发起 revoke_token。

1.2 同步登录与分步登录​

CloudBase CLI 对这套流程提供两种使用方式：

方式命令适用场景
同步登录tcb login用户直接在终端操作，允许当前命令持续等待授权完成
分步登录tcb login start + tcb login complete --session-id <sessionId>聊天工具、OpenClaw 类工具、机器人或远程执行器场景，需要先把授权信息返回给上层系统

同步登录​

tcb login

CLI 行为

  1. 申请设备码。
  2. 展示并尝试打开企业自建授权页。
  3. 轮询 /auth/token。
  4. 保存本地登录态。

分步登录​

tcb login start
tcb login complete --session-id <sessionId>

CLI 行为

  1. tcb login start 负责申请设备码并输出授权信息，同时在本地创建一个登录会话，返回 sessionId。
  2. tcb login complete 负责根据 sessionId 找回本地保存的设备码会话，在用户完成浏览器确认后继续轮询并完成登录。

1.3 工作流程​

2. 参考架构：基于参考实现的实现方式​

这一节开始引入参考实现。它的作用不是介绍仓库本身，而是把前面的协议和流程落到代码结构上。

参考实现仓库：cloudbase-cli-auth-endpoint

2.1 参考架构​

2.2 目录结构​

cloudbase-cli-auth-endpoint/
├── docs/
│   └── protocol.md              # 参考实现内部使用的协议说明
├── public/
│   └── cli-auth.html            # 企业自建授权页，输入 user_code 并确认授权
├── src/
│   ├── server.ts                # HTTP 入口，定义 /auth/device/code、/auth/device/verify、/auth/token
│   ├── config.ts                # 端口、过期时间、grant_type、STS 时长等配置
│   ├── types.ts                 # 设备码记录、refresh token 记录、请求体类型定义
│   └── utils/
│       ├── device-store.ts      # 设备码和 refresh token 的过期清理逻辑
│       ├── oauth.ts             # 设备码、用户码生成与 OAuth 错误结构
│       ├── sts.ts               # 调用腾讯云 STS 获取临时凭证
│       ├── tcb.ts               # 查询 envIds、envList、envBillingInfoList
│       └── public-dir.ts        # 静态页面目录解析
├── .env.example                 # 启动示例服务需要的环境变量
└── README.md                    # 本地运行和手工联调示例

2.3 参考实现流程​

启动与依赖​

参考实现启动前，至少需要准备以下环境变量：

PORT=3000
BASE_URL=http://localhost:3000
TENCENTCLOUD_SECRET_ID=xxx
TENCENTCLOUD_SECRET_KEY=xxx
STS_TOKEN_DURATION=1800

其中：

  1. BASE_URL 用来生成返回给 CLI 的 verification_uri。
  2. TENCENTCLOUD_SECRET_ID 与 TENCENTCLOUD_SECRET_KEY 用于调用腾讯云 STS 获取临时凭证。
  3. STS_TOKEN_DURATION 用于控制返回给 CLI 的临时凭证有效期。

准备完成后执行：

npm install
npm run dev

服务启动后，就可以配合前文的 CLI 登录流程进行联调。

首次登录流程​

续期与退出流程​

3. 企业可在参考实现基础上继续扩展的方向​

如果前面的流程已经跑通，后续企业通常会继续扩展这些能力：

  1. 把内存存储换成 Redis、数据库或中心化会话服务，避免服务重启后设备码和 refresh token 丢失。
  2. 把浏览器侧的简化用户信息，替换成企业自己的 SSO、IdP 或审批流结果。
  3. 把 STS 权限策略收敛成按用户、组织、环境隔离的最小权限策略。
  4. 再逐步补齐审计、限流、告警和可观测性。