为 CLI 客户端添加 OAuth 设备授权

概述

命令行工具既难以在远程 shell 中稳定开启本地回调，又不宜内嵌客户端密钥。设备授权流程让用户在浏览器中输入一个短码完成认证，CLI 通过轮询获得令牌，是 CLI 场景的标准做法。

关键步骤

1. 向授权服务器请求设备码与用户码。
2. 引导用户访问验证地址并输入用户码。
3. 按给定间隔轮询令牌接口直到授权完成。
4. 处理 slow_down 与 access_denied 响应，且绝不记录令牌。

验证

• CLI 无需本地回调即可获得令牌。
• 轮询遵守服务器给出的间隔。
• 授权失败时给出清晰提示。
• 令牌不出现在日志中。

注意事项

• 设备流程需要用户能使用浏览器，不适合完全无头的自动化。
• 它面向无法保管密钥的公共客户端；能保守秘密的机密客户端应使用授权码流程。

适用范围

本条目围绕「为 CLI 客户端添加 OAuth 设备授权」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

# 1. start
curl -s -d "client_id=$ID&scope=openid" https://auth.example.com/device_authorization
# 2. user visits https://auth.example.com/device and enters user_code
# 3. poll
curl -s -d "client_id=$ID&device_code=$CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code" https://auth.example.com/token