Skip to main content

Enterprise Self-built Device Code Authorization Service Integration with CloudBase CLI

This article explains how enterprises can use CloudBase CLI and self-built authorization services to complete specific integration, and implement the entire flow based on the reference implementation.

If you want to first understand the background and protocol specification of device code authorization, please read Device Code Authorization Overview first.

Self-built authorization service reference implementation repository: cloudbase-cli-auth-endpoint

1. How CloudBase CLI Works with This Flow​

1.1 Configure Authorization Service Address​

When an enterprise accesses this flow, first write the authorization service address into the CLI configuration. For example:

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

Replace https://auth.example.com/auth with the authorization service path you configured yourself.

Then execute:

tcb login

The reasons for doing this are:

  1. During first login, CLI will use this address to initiate device code authorization.
  2. After successful login, if refreshToken is saved locally, CLI will still need to know the same authorization service address when renewing.
  3. When the user executes tcb logout, CLI also needs to return to this address to initiate revoke_token.

1.2 Synchronous Login and Step-by-step Login​

CloudBase CLI provides two usage modes for this flow:

ModeCommandApplicable Scenario
Synchronous logintcb loginUser operates directly in the terminal, allowing the current command to wait continuously for authorization to complete
Step-by-step logintcb login start + tcb login complete --session-id <sessionId>Chat tools, OpenClaw-like tools, bots, or remote executor scenarios, which need to return authorization information to the upper-level system first

Synchronous Login​

tcb login

CLI Behavior:

  1. Request device code.
  2. Display and attempt to open the enterprise self-built authorization page.
  3. Poll /auth/token.
  4. Save local login state.

Step-by-step Login​

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

CLI Behavior:

  1. tcb login start is responsible for requesting the device code and outputting authorization information, while creating a login session locally and returning sessionId.
  2. tcb login complete is responsible for retrieving the locally saved device code session according to sessionId, and continuing to poll and complete login after the user completes browser confirmation.

1.3 Workflow​

2. Reference Architecture: Implementation Based on Reference Implementation​

This section introduces the reference implementation. Its purpose is not to introduce the repository itself, but to implement the previous protocol and flow into code structure.

Reference implementation repository: cloudbase-cli-auth-endpoint

2.1 Reference Architecture​

2.2 Directory Structure​

cloudbase-cli-auth-endpoint/
├── docs/
│   └── protocol.md              # Protocol specification used internally by the reference implementation
├── public/
│   └── cli-auth.html            # Enterprise self-built authorization page, input user_code and confirm authorization
├── src/
│   ├── server.ts                # HTTP entry point, defines /auth/device/code, /auth/device/verify, /auth/token
│   ├── config.ts                # Port, expiration time, grant_type, STS duration and other configurations
│   ├── types.ts                 # Device code record, refresh token record, request body type definitions
│   └── utils/
│       ├── device-store.ts      # Device code and refresh token expiration cleanup logic
│       ├── oauth.ts             # Device code, user code generation and OAuth error structure
│       ├── sts.ts               # Call Tencent Cloud STS to get temporary credentials
│       ├── tcb.ts               # Query envIds, envList, envBillingInfoList
│       └── public-dir.ts        # Static page directory parsing
├── .env.example                 # Environment variables needed to start the sample service
└── README.md                    # Local run and manual integration examples

2.3 Reference Implementation Flow​

Startup and Dependencies​

Before starting the reference implementation, you need to prepare at least the following environment variables:

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

Among them:

  1. BASE_URL is used to generate verification_uri returned to CLI.
  2. TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY are used to call Tencent Cloud STS to obtain temporary credentials.
  3. STS_TOKEN_DURATION is used to control the validity period of temporary credentials returned to CLI.

After preparation, execute:

npm install
npm run dev

After the service starts, you can perform integration testing with the aforementioned CLI login flow.

First Login Flow​

Renewal and Logout Flow​

3. Directions for Enterprises to Continue Extending Based on the Reference Implementation​

If the previous flow is already working, enterprises will typically continue to extend these capabilities:

  1. Replace in-memory storage with Redis, database, or centralized session service to avoid device codes and refresh tokens being lost after service restart.
  2. Replace the simplified user information on the browser side with the enterprise's own SSO, IdP, or approval flow results.
  3. Converge STS permission policies into minimum permission policies isolated by user, organization, and environment.
  4. Gradually improve auditing, rate limiting, alerting, and observability.