OAuth 2.0 Device Authorization Grant のバックアップ(No.9)

バックアップ一覧
差分を表示
現在との差分を表示
ソースを表示
OAuth 2.0 Device Authorization Grant へ行く。

「マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

戻る

目次 †

↑

概要 †

http://self-issued.info/?p=1959

と言った理由で、OAuth 2.0 Device Flowから変更された（v15から）。

↑

前提 †

Device（≒ Public Client）は、
1. 既にインターネットに接続されている状態。
2. アウトバウンドHTTPS要求を作成できる。
3. EndUser?（≒ Resource Owner）にURIとコードを表示できる。
EndUser?（≒ Resource Owner）は、
セカンダリデバイス（PCやスマホなど）を持っている。

↑

フロー †

+----------+                                +----------------+
|          |>---(A)-- Client Identifier --->|                |
|          |                                |                |
|          |<---(B)-- Device Code,      ---<|                |
|          |          User Code,            |                |
|  Device  |          & Verification URI    |                |
|  Client  |                                |                |
|          |  [polling]                     |                |
|          |>---(E)-- Device Code,      --->|                |
|          |          & Client Identifier   |                |
|          |                                |  Authorization |
|          |<---(F)-- Access Token      ---<|     Server     |
+----------+   (& Optional Refresh Token)   |                |
      v                                     |                |
      :                                     |                |
     (C) User Code & Verification URI       |                |
      :                                     |                |
      v                                     |                |
+----------+                                |                |
| End user |                                |                |
|    at    |<---(D)-- End user reviews  --->|                |
|  Browser |          authorization request |                |
+----------+                                +----------------+

ClientはAuthZ（N）Serverからの認可要求にclient_idを含める（A）。
AuthZ（N）Serverは、Clientの認可要求に対して下記を応答する（B）。
- デバイス・コード
- エンドユーザ・コード
- エンドユーザ検証URI
Clientは、EndUser?（≒ Resource Owner）に（別のデバイス上の）User-Agentを使用し、
エンドユーザ検証URIにアクセスしエンドユーザ・コードを入力するように指示（C）。
User-Agent
- AuthZ（N）ServerはUser-Agentを介しEndUser?（≒ Resource Owner）を認証。
- 許可要求に同意した場合、User-Agentからエンドユーザ・コードを入力、AuthZ（N）Serverで検証（D）。
Client
AuthZ（N）Serverを繰り返しPolling（デバイス・コードとclient_id）（E）
AuthZ（N）Serverは、
Clientから提供されたデバイス・コードとclient_idを検証し、
EndUser?（≒ Resource Owner）が、アクセスを、
- 許可した場合はaccess_tokenで応答し、（F）
- 拒否した場合はエラーを返す。

↑

詳細 †

↑

認可エンドポイント †

認証リクエストを受け付けて直ちにレスポンスする（以後、非同期的に処理）。

↑

認可リクエスト †

ポイントは
- POSTであること。
- client_secretは不要。

リクエスト例

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

client_id=459691054427

↑

認可レスポンス †

パラメタ

device_code
- 必須。
- デバイス・コード（デバイスを検証するコード）。
- 高いエントロピーを要求（GUID位の長さか？）

user_code
- 必須。
- エンドユーザー確認コード。
- BCDFGHJKLMNPQRSTVWXZ(基数20)から8文字(XXXX-XXXX)
- 9桁の有効数字（nnn-nnn-nnn）

validation_uri
- 必須
- 承認のエンドユーザー検証URI
- 手動入力可能なように短く。

validation_uri_complete
- オプション。
- QueryString?にuser_codeを含むvalidation_uri
- QRコードやNFCなどのURIでブラウザが開かれる方法を使用する。

expires_in
- 必須
- device_code、user_codeの有効期間（秒）。

interval
- オプション。
- Polling間隔
  最小の待機時間（秒）
  デフォルトは5（秒）

レスポンス例

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "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
}

↑

エラーの返却 †

POSTのJSON返却なので、Tokenエンドポイントのレスポンス（失敗）と同じ。

↑

ユーザへの指示 †

Resource Owner（EndUser?）への指示。

user_code and verification_uri
verification_uri_complete (optional)

※ device_codeは、混乱を招くため、対話中に表示しない。

↑

表示例 †

「verification_uri」

+-----------------------------------------------+
|                                               |
|  Using a browser on another device, visit:    |
|  https://example.com/device                   |
|                                               |
|  And enter the code:                          |
|  WDJB-MJHT                                    |
|                                               |
+-----------------------------------------------+

「verification_uri」 and 「verification_uri_complete (by QR code)」

+-------------------------------------------------+
|                                                 |
|  Scan the QR code, or using     +------------+  |
|  a browser on another device,   |[_]..  . [_]|  |
|  visit:                         | .  ..   . .|  |
|  https://example.com/device     | . .  . ....|  |
|                                 |.   . . .   |  |
|  And enter the code:            |[_]. ... .  |  |
|  WDJB-MJHT                      +------------+  |
|                                                 |
+-------------------------------------------------+

その他

テキスト読み上げオーディオ

Bluetooth Low Energy（BLE）による
- 非ブラウザユーザーインタラクション（コンパニオンアプリの利用）
- ただし、verification_uri以外の操作は使用の範囲外。

↑

手順 †

Resource Owner（EndUser?）は、AuthZ（N）Server の verification_uri（HTTPS）に移動、
user_codeを入力し、AuthZ（N）Serverに送信（デバイス認可セッションの識別のため）
※ user_code入力画面への遷移前のサインアップ、追加のセキュリティ検証などの手順を追加可能。
この後に表示される画面で、同意 / 拒否を回答して、AuthZ（N）Serverに再送信。
Device（≒ Public Client）はdevice_codeでTokenエンドポイントを継続的にPolling
- ユーザーが対話を完了するか、
- コードが期限切れになるか、
- 別のエラーが発生するまで。

↑

セキュリティ考慮事項 †

user_code入力の試行回数は、5回（アルファベットで8文字程度）。

↑

Tokenエンドポイント †

↑

Tokenリクエスト †

デバイス上のプロンプトに表示した後、TokenリクエストのPollingを始める。

パラメタ
- grant_type=urn:ietf:params:oauth:grant-type:device_code
- device_code
- client_id

リクエスト例

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
&client_id=459691054427

↑

Tokenレスポンス †

成功
OAuth 2.0の認可レスポンス（成功）と同じ。

失敗
OAuth 2.0の認可レスポンス（失敗）に以下のパラメタを追加

パラメタ（≒エラーコード）

authorization_pending
認可リクエストは保留中

slow_down
"authorization_pending"の変形で
Polling間隔を5秒遅らせろの意味。

access_denied
Resource Owner（EndUser?）は、承認要求を拒否。

expired_token
device_codeの有効期限が切れ。

レスポンス例

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"authorization_pending"
}

↑

ポイント †

Pollingなので、

過負荷にならないように注意する。
Exponential Backoff（指数関数的に増えるリトライ間隔）推奨
- タイムアウト時、指数関数的にリトライ間隔を後退
- 1秒、2秒、4秒、8秒、16秒とリトライ間隔を後退させる

自動的ではなく、デバイス上のプロンプトに
表示された場合にのみデバイス認証要求～Pollingを開始するなど。

Polling以外の選択肢
- リターンチャネルが存在する場合、Polling以外の選択肢も選択可能。
- しかし、このような動作はこの仕様の範囲外
  （CIBAではコレを仕様で決めているがCDはDeviceでは無いな...）。

クライアント認証
client_id と device_code（client_secret）

↑

その他 †

↑

メタデータ †

grant_types_supported に urn:ietf:params:oauth:grant-type:device_code を追加。
エンドポイントとして、device_authorization_endpoint を追加。

↑

セキュリティ考慮事項 †

Deviceは、Public Clientで、PKCEとの違いは、
認可リクエストと実際の認可を行うデバイスが異なる事。

認可を行うデバイスは信頼できるが、
認可リクエスト、Tokenリクエストを行うデバイスの信頼性は微妙

なので、device_code を client_secret代替として使用する。
（紐付けのタメのuser_codeは、実際の認可を行うデバイスから入力する）

中間者攻撃
- Device購入者は、Deviceと開発・販売元が信頼できると期待している。
- これがハズれると、中間者攻撃が成立してしまうことがある。

フィッシング
- e-mailやSMSで validation_uri_completeを使用すると、
  フィッシング攻撃が成立してしまうことがあるので使用しない。

認可レスポンスのexpires_inを、
いい塩梅に設定する（長過ぎず、短過ぎず）。

device_code と user_codeの盗難

セッションスパイ
ショルダーハッキングのような。ディスプレイでか過ぎとか無いよね。

ブートストラップ
通信チャネルは、デバイスの近くでのみ有効なものを選択する（見る、聞く、BLE）。

↑

参考 †

2019年8月にDraftからRFC化がされている。

RFC 8628 - OAuth 2.0 Device Authorization Grant
https://tools.ietf.org/html/rfc8628

OAuth 2.0 Device Authorization Grant
（draft-ietf-oauth-device-flow）
https://tools.ietf.org/html/draft-ietf-oauth-device-flow

↑

目次 †

概要 †

前提 †

フロー †

詳細 †

認可エンドポイント †

認可リクエスト †

認可レスポンス †

エラーの返却 †

ユーザへの指示 †

表示例 †

手順 †

セキュリティ考慮事項 †

Tokenエンドポイント †

Tokenリクエスト †

Tokenレスポンス †

ポイント †

その他 †

メタデータ †

セキュリティ考慮事項 †

参考 †

内部リンク †

OAuth 2.0 Device Flow †

CIBA(Client Initiated Backchannel Authentication) †