前言

上一篇 Day 12 談的是 Client Credentials Grant——完全不需要使用者參與的機器對機器（M2M）情境。今天要回到「有使用者」的場景，但使用者手上的裝置不太一樣：智慧電視、遊戲主機、IoT 裝置、CLI 工具⋯⋯這些裝置常常沒有瀏覽器，或是輸入能力很差。OAuth 2.0 針對這種情境定義了 Device Authorization Grant（RFC 8628），俗稱 Device Flow。

今天內容涵蓋

1. Device Authorization Grant 是什麼、適用場景
2. 流程總覽：Device Flow ＋ Browser Flow
3. Device Authorization Request／Response 格式
4. Device Access Token Request／Response 與輪詢機制
5. 安全考量

一、什麼是 Device Authorization Grant

RFC 8628 的 Abstract 說得很明楚：這個 Grant 是為了「連上網路，但缺乏瀏覽器、或輸入能力受限到無法在授權流程中輸入文字」的裝置設計的，例如智慧電視、媒體主機、數位相框、印表機。它讓這些裝置上的 OAuth Client，可以透過使用者在「另一台裝置」上的使用者代理（瀏覽器）完成授權。

RFC 8628 §1 也列出了使用這個 Grant 的四個前提條件：

1. 裝置已經連上網路
2. 裝置能發出對外的 HTTPS 請求
3. 裝置能顯示或以其他方式傳達一組 URI 和代碼給使用者，例如顯示網址與 user_code，或提供 QR Code 讓使用者用手機掃描
4. 使用者擁有一台「次要裝置」（電腦或智慧型手機），可以用來處理這個請求

因此，Device Authorization Grant 主要用於缺乏瀏覽器、或文字輸入能力受限的裝置。若是智慧型手機這類可以正常開啟瀏覽器、接收重新導向的原生 App，通常仍應採用前面介紹過的 Authorization Code + PKCE，而不是改用 Device Flow。

常見的適用場景：

• Smart TV／機上盒：YouTube、Disney+ 這類服務在電視上顯示一組代碼，要求使用者拿手機或電腦到指定網址輸入代碼完成登入
• 遊戲主機／無瀏覽器功能的穿戴裝置：例如在遊戲主機或沒有完整瀏覽器功能的手錶上登入服務時，使用者改用手機或電腦完成授權
• 會議室裝置：Zoom 官方 App 在視訊會議裝置上的登入
• CLI 工具：GitHub CLI、雲端服務的命令列工具，在終端機環境中安全完成授權，不用自己處理帳密
• IoT 裝置：印表機、視訊編碼器等沒有螢幕鍵盤的裝置

二、流程總覽：Device Flow ＋ Browser Flow

Device Authorization Grant 其實包含兩條並行的路徑：一條發生在「裝置本身」（Device Flow），另一條發生在使用者的「瀏覽器」（Browser Flow）。裝置會先向 Authorization Server 取得代碼，接著把驗證網址與使用者代碼顯示給使用者；使用者改用手機或電腦完成登入與授權，裝置端則持續輪詢 Token Endpoint，等待授權完成後取得 Access Token。

以上圖來看，流程可以拆成十個步驟：

1. Device Client 請求授權：Device Client 帶著 client_id 與 scope，向 Authorization Server 的 Device Authorization Endpoint 發出請求。
2. Authorization Server 回傳代碼：Authorization Server 回應 device_code、user_code、verification_uri，以及有效時間與輪詢間隔等資訊。
3. 裝置顯示操作指示：Device Client 將 verification_uri 與 user_code 顯示給使用者，或提供 QR Code，請使用者改用另一台裝置操作。
4. 使用者開啟驗證頁面：End User 使用手機或電腦的瀏覽器造訪 verification_uri。
5. 輸入使用者代碼：Authorization Server 要求使用者輸入 user_code，用來對應原本那台等待授權的裝置。
6. 完成登入與同意授權：使用者在瀏覽器中完成登入，並同意 Device Client 要求的授權範圍。
7. Device Client 輪詢 Token Endpoint：在使用者完成授權前後，Device Client 會依照 interval 指定的輪詢間隔，持續帶著 device_code 向 Token Endpoint 查詢授權是否完成。
8. Authorization Server 回傳 Token：使用者完成授權後，Authorization Server 在下一次輪詢回應中回傳 Access Token，視設定也可能包含 Refresh Token。
9. Device Client 呼叫 API：Device Client 帶著 Access Token 呼叫 Resource Server / API，請求存取受保護資源。
10. Resource Server 回傳資源：Resource Server 驗證 Access Token 後，回傳對應的資料或受保護資源。

整段流程中，裝置與使用者瀏覽器沒有直接的雙向通訊。使用者在瀏覽器端完成「授權確認」；裝置端則透過輪詢 Token Endpoint 得知授權是否完成。這也是它和 Authorization Code Grant 最大的不同：Device Flow 不需要瀏覽器重新導向回原本的裝置。

三、Device Authorization Request／Response：先取得裝置代碼（RFC 8628 §3.1–3.2）

從這一節開始，會把流程中的 HTTP 請求與回應拆開來看。

第一個階段對應流程圖的步驟 1、2。Device Client 會先向 Authorization Server 的 Device Authorization Endpoint 送出請求，要求建立一組本次授權流程使用的代碼：device_code 給裝置端後續輪詢使用，user_code 則顯示給使用者，讓使用者在另一台裝置上完成驗證。

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

成功時，Authorization Server 回傳 200 OK。這個回應的重點，是把「給裝置用」和「給使用者用」的資訊分開：

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete": "https://example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

Device Client 拿到 device_code 之後，還不能直接取得 Access Token；它必須等使用者在另一台裝置完成登入與授權，再用 device_code 去 Token Endpoint 查詢結果。

四、輪詢 Token Endpoint：等待使用者完成授權（RFC 8628 §3.4–3.5）

取得 device_code 後，Device Client 接下來要做的事情，是定期向 Token Endpoint 查詢授權結果。

這也是 Device Flow 和 Authorization Code Grant 很大的差異。Authorization Code Grant 會透過瀏覽器的 redirect_uri 把結果導回 Client；但 Device Flow 面對的是 Smart TV、遊戲主機、CLI 或 IoT 裝置，因此改用「輪詢」的方式，主動向 Authorization Server 查詢：使用者完成授權了嗎？可以核發 Access Token 了嗎？

Device Client 輪詢 Token Endpoint 時，grant_type 固定使用 Device Code Grant 的識別值：

urn:ietf:params:oauth:grant-type:device_code

送到 Token Endpoint 的請求通常會包含以下參數：

輪詢時，Device Client 不能無限制地一直送請求。它應該依照回傳的 interval 等待指定秒數後再查詢；如果回應中沒有 interval，就使用預設的 5 秒作為輪詢間隔。例如 interval: 5 代表 Device Client 至少要等 5 秒，才能再次向 Token Endpoint 查詢授權狀態。

在使用者完成授權之前，Device Client 通常還拿不到 Access Token。這時 Token Endpoint 不會直接回傳成功結果，而是用錯誤碼告訴 Client 目前流程進行到哪裡：

只有 authorization_pending 和 slow_down 代表「流程尚未結束，可以繼續等待」。收到 access_denied 或 expired_token 時，Device Client 就不應再繼續輪詢，而是應該停止流程並把結果呈現給使用者。

等使用者在瀏覽器端完成登入與授權後，Authorization Server 會在下一次輪詢時透過 Token Endpoint 回傳 Access Token；視設定不同，也可能一併回傳 Refresh Token。

五、安全設計與潛在風險

Device Authorization Grant 的安全設計，重點是避免使用者在輸入受限、缺乏完整瀏覽器的裝置上直接輸入帳號密碼。它會把登入與同意授權移到手機或電腦的瀏覽器中完成，原本的 Device Client 只負責顯示代碼、等待結果，並在授權完成後透過 Token Endpoint 取得 Access Token。

因此，Device Flow 不是保證「一定安全」，而是透過幾個設計降低風險：

不過，這些設計只能降低風險，不能消除所有風險。Device Flow 仍然需要注意以下問題：

所以，Device Authorization Grant 的安全性取決於 Authorization Server 與 Client 是否正確實作這些限制。比較好的實作會縮短代碼有效期限、限制錯誤嘗試次數、強制使用 HTTPS、限制代碼只能使用一次，並在驗證頁面清楚顯示正在授權的裝置與權限範圍。

小結

Device Authorization Grant 的重點，是讓「不好輸入帳密、也不適合跑完整瀏覽器流程」的裝置，透過另一台裝置完成使用者授權。

這裡最容易混淆的是 user_code 和 device_code：

• user_code 是給使用者看的代碼，會顯示在裝置畫面上，讓使用者到另一台裝置的瀏覽器輸入。
• device_code 是給 Device Client 使用的代碼，不應顯示給使用者；裝置會用它輪詢 Token Endpoint，確認授權是否完成。

因此，Device Flow 並不是讓登入變得「絕對安全」，而是把帳密輸入移到比較適合的瀏覽器環境中處理，再透過短效代碼、輪詢間隔、錯誤限制與使用者確認，降低風險。

下一篇要看的是 JWT Bearer Grant。它和 Device Authorization Grant 不同，不是讓使用者換到另一台裝置完成授權，而是讓 Client 拿一份已簽章的 JWT Assertion，向 Authorization Server 換取 Access Token，常見於企業內部系統或服務對服務的授權場景。

參考資源

• Auth0 – Device Authorization Flow
• Auth0 – Call Your API Using the Device Authorization Flow
• Logto Auth Wiki – 裝置流程 (Device flow) 是什麼？
• oauth.net – OAuth 2.0 Device Authorization Grant
• RFC 8628 – OAuth 2.0 Device Authorization Grant
• Authgear – 常見 OAuth 2.0 授權類型與適用時機完整指南
• Microsoft Learn – Device code flow (MSAL Java)
• Curity – OAuth Device Flow