繁體中文（香港）
  • cli
  • oauth
  • security
  • ai-tools

搞懂 CLI 認證的 4 大方法：完整攻略

重點介紹最重要的 4 種 CLI 認證方法、GitHub、AWS 和 AI 工具如何實現它們，以及常見的安全錯誤，幫你避開坑。

Yijun
Yijun
Developer

Stop wasting weeks on user auth
Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.
Get started
Product screenshot

每個開發者 CLI 的第一個指令幾乎都是 login，但每套 CLI 都用不同的方式處理認證。

GitHub 會顯示一組代碼，並幫你打開瀏覽器驗證。AWS 則用瀏覽器開啟基於 PKCE 的 SSO。Stripe 則是在 dashboard 上確認配對碼。新一代的 AI 工具（Claude Code、OpenAI Codex CLI、Cursor）都有自己獨特的認證流程。

如果你要建立一套 CLI，認證一定要先規劃清楚。方法選錯，保證被投訴：用戶抱怨、被審計，甚至兩樣都有。近年 AI 寫碼 agent 開始自動化調用 CLI 工具，安全性重要性更高：你不只在驗證真人，還可能交出密鑰給自動程序。

以下是最關鍵的四種 CLI 認證方式、各大主流工具的實例，以及常見錯誤避坑指南。

四種主要方法一覽

先來張快速比較表：

方法最適用情境安全性需否用瀏覽器？
OAuth Device Code FlowHeadless 環境、SSH高不需（同一機器完全不需）
瀏覽器 OAuth（localhost redirect）本機開發最高需要
API Keys / PATs自動化、CI/CD、快速原型中等不需要
Client Credentials機器對機器、服務高不需要

每種方法都有取捨，下面詳細展開分析。

1. OAuth device code flow（RFC 8628）

這種方式就是 CLI 會顯示代碼如 ABCD-1234 及一個網址，然後叫你用任何裝置開網址輸入代碼。

常用工具： GitHub CLI（預設）、Azure CLI（用 --use-device-code）、Vercel CLI（新版預設）、OpenAI Codex CLI（beta）

運作方式

  1. 你執行 cli login
  2. CLI 想認證伺服器請求一個 device code，傳 client_id 和權限範圍
  3. 伺服器回傳 3 件事：device_code（內部用）、user_code（你要輸入的短碼）和 verification_uri（去哪驗證）
  4. CLI 顯示代碼和網址，開始每 5 秒輪詢詢問 token 狀態
  5. 你在 任何 裝置（手機、筆電、另一台電腦）開網址，輸入代碼，再用密碼／SSO／MFA 等驗證
  6. 一旦認證同意，下次輪詢會取得 access token 和 refresh token
  7. CLI 寫入相關憑證，開始登入流程

開發者為什麼愛用

最大賣點：哪裡都能用。SSH 登遠端可以，Docker 容器可以，沒本機瀏覽器的 Cloud IDE 可以。瀏覽器根本不用在同一台機上。

而且支援企業各種複雜 SSO（SAML、OIDC、MFA）——全在瀏覽器端進行，CLI 根本拿不到你密碼。

常被忽略的安全缺口

Device code flow 有網釣風險。攻擊者可以申請一組 code，然後騙你去授權，最後其實把 access 權限交給了攻擊端。這不是理論，AWS SSO device code flow 就曾被安全研究員證實此漏洞。

嚴重到 AWS 已修改預設值：AWS CLI v2.22.0 起，aws sso login 預設不再是 device code，而改為 PKCE 的授權碼流程。device code 還能用 --use-device-code 選項啟用，但官方已不推薦。

同時，Microsoft 自家租戶 已逐步限制使用 device code flow（透過條件存取政策），可見他們也認為這是高風險認證方式。

出現有趣分裂：Vercel 升級 device code 為預設（2025 年 9 月），AWS 則反而 去預設化。顯示 device code flow 適合 真的無法開本機瀏覽器 的環境。若能打開本機瀏覽器，PKCE 更安全。

從認證服務供應商趨勢來看，需求持續上升。Logto 已在 v1.38.0（開源及雲端）支援 OAuth 2.0 Device 授權 grant，現在你可隨時開啟 device flow，給任何 native app 用。重點是：若你要實作 CLI，正確完成 RFC 8628 其實不容易（要處理 code 過期、輪詢節流、頁面 UX），交給供應商支援會省工程量，你只需正確發 HTTP request 即可。

RFC 技術重點

RFC 8628 幾個須知事項：

  • expires_in（device code 有效期）由認證伺服器定，舉例 1800 秒（30 分鐘），但不硬性規定。
  • 若伺服器沒提供 polling interval，client 須預設用 5 秒。
  • 收到 slow_down error，要多加 5 秒間隔。
  • device code 需單次使用並且快速過期。
  • 所有 token 交換必須走 HTTPS。

2. 瀏覽器 OAuth（localhost redirect）

這是本地開發最常見的做法。開 login，自動用預設瀏覽器跳轉，瀏覽器驗證後再 redirect 回 CLI 開的 localhost server。現代實作會加 PKCE（"pixie"），極大提升安全。

採用工具： Claude Code、gcloud CLI、Terraform CLI、AWS CLI v2.22+（SSO 預設啟用 PKCE）

運作流程

  1. 執行 cli login
  2. CLI 在本機隨機端口開 HTTP server（例：http://127.0.0.1:8742）
  3. 用預設瀏覽器打開認證授權端點，傳 localhost URL 作為 redirect URI
  4. 你在瀏覽器做各種驗證（SSO、密碼、MFA……）
  5. 認證服務將瀏覽器重導回 http://127.0.0.1:8742/callback?...
  6. local server 抓到授權 code，透過 HTTPS 資交換 token
  7. 瀏覽器顯示「成功！請關閉視窗」頁面
  8. CLI 儲存 token，關掉 local server

體驗非常順，不用複製代碼、不用手打網址，瀏覽器來回點下就搞定。

何時失效

此流程需要 CLI 能夠：

  • 開啟本機 browser
  • 綁定本地端口

下列情境不適用：

  • SSH 進遠端主機
  • Docker 容器（除非你用 port-forward 技巧）
  • CI/CD pipeline
  • 無頭（headless）伺服器
  • 某些公司限制嚴格環境

所以各家 CLI 會預設 browser OAuth，並用 device code 或 API key 做 fallback。

三個常見安全踩雷點

雷一：不小心綁到 0.0.0.0 而不是 127.0.0.1

這個錯常見而且很嚴重。如果 callback server 監聽所有網路介面，局域網任何人都攔得到授權 code。

不少 CLI 曾出現在實作裡，因為很多 HTTP server library 的預設就有這個問題。

雷二：沒驗證 state 參數

state 是 CSRF 保護。沒驗證，攻擊者可以給你假的 code，導致實際權限被他拿到。

雷三：沒用 PKCE

沒有 PKCE（Proof Key for Code Exchange）的 OAuth 流程，授權碼一旦落入惡意方手中就會被盜用。

標準流程下，攻擊者如果攔截到授權 code，可直接拿來換 token。PKCE 可以防住這一招，即便對方攔截 URL 也無法兌換。

PKCE 主要流程：

  1. CLI 產生高熵隨機 code_verifier
  2. 用 SHA-256 哈希產生 code_challenge
  3. challenge 隨初始授權請求送給認證伺服器
  4. 換 token 時送原本的 code_verifier
  5. 伺服器確認 challenge 是否配對

攔截到 code 的人沒有 verifier，所以無法交換。

這正是 AWS CLI v2.22+ 改走 PKCE 為 SSO 預設，捨棄 device code。CLI 能夠開 browser 的話，browser OAuth + PKCE 安全性完勝 device code——體驗相同，風險更低。不過要是在 SSH、容器等沒法開本機瀏覽器時，才建議用 device code。

3. API keys 及個人存取權杖（PAT）

最簡單的做法。你在網頁 dashboard 生成一串 token，貼進 CLI 設定檔或環境變數就行。

常見工具： Stripe CLI（可選 login 方式）、npm、pip、多數 AI coding 工具（Claude Code 用 ANTHROPIC_API_KEY，OpenAI 工具用 OPENAI_API_KEY，Aider 等）

運作流程

  1. 登入網頁管理台
  2. 從設定 → API 金鑰區產生新 key（長字串且可能有 prefix，如 sk_live_, ghp_ 等）
  3. 儲存到 config 檔（如 ~/.config/stripe/config.toml、~/.aws/credentials）或環境變數

CLI 會在啟動時讀入常用的 API key，然後用 Authorization: Bearer header 送出 API 請求。

優點 / 受歡迎緣由

自動化情境，API 金鑰效率無敵。CI/CD、容器、腳本、排程都能用，不需瀏覽器、不需人工互動或 refresh 流程。

AI 代理更是最愛：Claude Code、Cursor 等用 environment variable 能直接整合。

風險與缺點

  • 外洩。 API 金鑰常被誤放進 git、log、錯誤訊息、CI 輸出等，GitHub 每年偵測到百萬筆外洩。
  • 權限過大。 多數 API key 權限範圍太大，外洩即大崩潰。
  • 無 MFA。 API 金鑰繞過 multi-factor 設定。
  • 難以輪換。 只要要輪換就要到各處手動更新，大團隊很難同步。

現代最佳實踐：臨時 token 交換

聰明做法是：用 API key 換短期 token，運行時臨時授權。

AWS 最早搞這個（STS = Security Token Service）。長效憑證僅用來換 1 小時臨時證書。aws-vault 等工具自動搞定輪換。

就算必須用 API key，也推薦加入此設計。這能把密鑰外洩損失窗口從「隨時失效」降為「1 小時內」。

4. Client credentials flow

這個 OAuth 2.0 流程是給機器與機器間溝通用的，無人參與。

主要場景： CI/CD pipeline、背景服務、全自動工具

運作方式

服務端直接傳 client_id 和 client_secret 給認證伺服器，獲得一組短效 access token。不需瀏覽器、不需互動。

適用場景

適用於：

  • 機器（或 bot）自動登入，不需要真人介入
  • 在 CI/CD pipeline
  • 需全自動存取
  • 「使用者」本身就是應用程式

不要用來做真人驗證——沒法支援 MFA、SSO 或互動驗證。

主流 CLI 實際用例

整理一下實際官方做法與原始碼（因為資訊常變動，很多網文寫錯）。

CLI 工具預設認證備用選項Token 儲存方式
GitHub CLI (gh)Device code flow（瀏覽器）PAT（--with-token）、env var（GH_TOKEN）OS keychain（備用：純文字檔案）
AWS CLI v2PKCE 授權碼流程（SSO）Device code（--use-device-code）、憑證檔~/.aws/sso/cache/
Azure CLI (az)Windows 下用 WAM；Linux/macOS 用瀏覽器授權碼Device code（--use-device-code）~/.azure/msal_token_cache.*
Vercel CLIDevice code flow（2025/9 預設）API token（--token、env var）~/.local/share/com.vercel.cli/auth.json
Stripe CLI瀏覽器配對流程API key（--interactive、--api-key 或 env var）~/.config/stripe/config.toml
gcloud CLI瀏覽器 OAuth--no-browser 手動流程~/.config/gcloud/
Claude Code瀏覽器 OAuthAPI key（env var、apiKeyHelper）OS keychain / ~/.claude/.credentials.json
OpenAI Codex CLI瀏覽器 OAuthDevice code（beta）、API key~/.codex/auth.json / OS keyring
Terraform CLI瀏覽器 OAuthToken 貼上~/.terraform.d/credentials.tfrc.json

趨勢已很清楚：**本機預設都是 browser OAuth，無頭備用 device code，自動化則仍採用 API key。**瀏覽器可用時，PKCE 是目前最安全方案。

Token 儲存策略

認證做得再好，Token 存錯也白搭。

最佳做法：OS keychain

三大系統都有內建加密憑證庫：

  • macOS： Keychain（GitHub CLI、Claude Code 採用）
  • Windows： Credential Manager
  • Linux： Secret Service API（GNOME Keyring、KDE Wallet）

這些都有 OS 層級加密、存取控管、硬體安全整合。你不需自己實作加密。

備用方案：加密設定檔

若 keychain 無法使用（如容器環境、極簡 Linux），用只限 owner 的加密設定檔即可：

千萬避開

純文字檔。 看似基本但仍有許多工具還在用。任何同用戶進程、備份程式、甚至臨時入侵者都查得到。

長期存環境變數。 Env var 會暴露在進程列表、經常被 crash 報告或子進程遺漏記錄。CI/CD 用可，但本地開發風險大。

瀏覽器 localStorage。 CLI 若帶 web 元件千萬別丟 localStorage。有 XSS 你直接全軍覆沒。

Token 生命周期管理

Access token

請設定短效。1 小時已是業界準則。過期後 CLI 要自動 refresh，不該強迫用戶一直重新登入。

Refresh token

Refresh token 是長效密鑰，主要用來兌換新 access token。攻擊者最愛，效期更久（數天或數月）。

Refresh token 輪換機制

現代認證服務會每次用 refresh token 都配套產生新的一組：

  1. CLI 用 refresh token 換 access token
  2. Server 回新 access token 和 新 refresh token
  3. 舊的 refresh token 立即失效
  4. CLI 儲存兩個新 token

這能封殺盜用場景。若攻擊者用你的舊 refresh token，auth server 偵測重用情況，一次性封存整個家族，正當用戶與攻擊者都要重登入，但能阻止後者繼續存取。

常見地雷（附代碼）

1. callback server 綁全體網卡

詳細已上段，但務必重申：堅持只綁 127.0.0.1，切勿用 0.0.0.0。

2. token 被 log

大家都做過。debug log，錯誤 handler，verbose mode ...

3. 將金鑰 bake 進容器 image

Docker image 並不是「祕密庫」，每層都能取出內容。

4. 沒優雅處理 token 過期

token 臨時過期不要直接炸出 401 error。先嘗試 refresh，若 refresh 也過期才提示重登入。

5. 忽略最小權限原則

不要要任何 admin:* scope，只因你只要 repo:read。OAuth scope、API key 權限都適用。

AI agent 用 CLI 時尤其重要——你不希望 assistant 能刪 repo，只因他要讀 code。

AI agent 新挑戰

2026 年特殊點是：CLI 不再只是人用，AI coding agent（Claude Code、Codex、Cursor agent 模式）也會程式化調用 CLI 工具。這帶來全新認證挑戰：

權限下放問題。 Claude Code 幫你 gh pr create 時，是用你的 GitHub 憑證。但 AI agent 應該拿你全部權限嗎？最小權限原則說不該，但多數工具還不能將權限細切給代理。

憑證外洩風險。 API key 放環境變數的話，任何進程（包含 AI agent 的子進程）都能看到。Claude Code 開發了 apiKeyHelper 這類 script 產生短期 token 以控管風險，但業界還沒統一。

代理專用無頭認證。 AI agent 若在沙盒內運行，無法開啟瀏覽器。這時 device code 方案適合（讓人去另一台機器輸入驗證授權），但多數 agent 還是採 API key，因為完全不用人工。

稽核困難。 Agent 用你的 token 做 API call，稽核 log 上都只看見你的行為。當前沒標準可區分「用戶自己做的」跟「AI 代理代做」。

這塊還在急速演進。你現在能做的：

  • 給 agent 流程專屬 scope、最小權限 token
  • 盡量使用短期憑證（臨時 token，別用長期 API key）
  • 員工自己密鑰跟 agent 用的密鑰分開
  • 定期監控 API 行為是否有異常

選擇建議

怎麼挑認證法？總結如下：

「目標使用者是本機開發者」 → Browser-based OAuth + PKCE（最安全 UX 又好）

「CLI 要能在 SSH/容器裡用」 → device code 備用，browser OAuth 為主

「給 CI/CD 無人值守用」 → client credentials flow 或 API key

「求最快搞定」 → 先用 API key（後續再補 token 輪換）

「企業客戶需 SSO, MFA」 → 任何 OAuth（device code 或 browser）都能支援企業級認證

「AI agent 要用 CLI」 → 支援 API key（方便 agent 集成）＋ browser OAuth（給真人用），而且權限細切、token 壽命盡量短

FAQ

device code flow 安全嗎？

對大多數攻擊很安全，但有已知的 phishing 風險。攻擊者可以產出 device code 誘騙用戶授權。AWS 就因此把 SSO 登入預設改為 PKCE。無法用瀏覽器的情境 PKCE 不適用時，device code flow 還是最佳選。只是要風控詐騙攻擊。

token 能存環境變數嗎？

CI/CD 可以，因為平台會加密儲存、runtime 注入；本機開發不建議。改用 OS keychain，因 env var 在 process list 可見，也易誤寫 log 或被子進程繼承。

API key 跟 Personal Access Token 差在哪？

本質差異不大，兩者都是長效認證 API 的憑證。區分在於組織架構：API key 常綁「專案或應用」，PAT 常綁「用戶帳號」。有些服務兩詞本來就交錯用。

憑證要多久輪換一次？

Access token：每小時自動（refresh flow 處理）。Refresh token：每次 refresh 都輪換（auth server 做）。API key：最少 90 天換一次，或有風險立即換。實務上多半等發現外洩才換，這太慢了。

Docker 容器怎麼認證？

依優先：

  1. Device code flow 互動情境（可用其他裝置操作 browser）
  2. 環境變數 runtime 傳入（docker run -e API_KEY=${API_KEY}），適合 CI/CD
  3. 掛 volume 的憑證檔（docker run -v ~/.config/tool:/root/.config/tool:ro），適合本地開發

金鑰千萬別寫進 image。本地測試也別。永遠不要。

MCP（Model Context Protocol）認證呢？

MCP 是 AI agent 與外部工具服務連線的新標準，帶來新類型的認證問題：代理 client 本身要有對 MCP server 的憑證，而 MCP server 自己還要管理下游 API 的憑證。這規格還在演進，目前多用 API key 或 OAuth token 配進 MCP 設定檔。未來還會快速迭代。

CLI 認證標準正在快速變化。過去（兩年前）流行 device code + 純文字檔案，如今已被淘汰。若你現在加 CLI 認證，請以 browser OAuth + PKCE 為主（真人）、API key 做自動化，並做好 AI agent 主導未來的準備。