OAuth 2.0 Device Flow

Last updated 5 months ago

OAuth 2.0 Device Flow for Browserless and Input Constrained Devices 和訳例

はじめに

本和訳は個人で作成・公開している、あくまで例であり、意訳や間違いが含まれておりますことをご了承ください。

コメントや誤り指摘等は、Twitter @sami_mkw_ までいただけますと幸いですm(_ _)m

OAuth 2.0 Device Flow for Browserless and Input Constrained Devices

要旨(Abstract)

ブラウザレスや入力制約付きデバイス向けのOAuth2.0認可フローは,デバイスフローとも呼ばれている. OAuthクライアントは,インターネット接続はあるけれども 簡単に入力する方法がなかったり,伝統的なOAuthフローに適切なブラウザが存在しなかったりするデバイス (スマートTV,メディア・コンソール,ピクチャー・フレーム,プリンタなど)でもユーザ認可をリクエストすることが可能になる.この認可フローでは,ユーザのスマートフォンなど,二次デバイスで認可リクエストを実行する.制約のあるデバイスと二次デバイスとの間の通信は必要ない.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on October 22, 2018.

Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

1. 導入(Introduction)

ブラウザレスや入力制約付きデバイス向けのOAuth2.0認可フローは,デバイスフローとも呼ばれている. OAuthクライアントは,インターネット接続はあるけれども 簡単に入力する方法がなかったり,伝統的なOAuthフローに適切なブラウザが存在しなかったりするデバイス (スマートTV,メディア・コンソール,ピクチャー・フレーム,プリンタなど)でもユーザ認可をリクエストすることが可能になる.この認可フローでは,ユーザのスマートフォンなど,二次デバイスで認可リクエストを実行する.制約のあるデバイスと二次デバイスとの間の通信は必要ない.

デバイスフローは,スマートフォンなどの有能なデバイスのネイティブアプリにおけるブラウザベースのOAuthを置き換えるためのものではない.そのようなアプリは,ネイティブアプリ向けのOAuth 2.0 for Native Apps [RFC8252]で規定されている仕様に従う必要がある.

このフローが採用される場合の唯一の要件は,デバイスがインターネットに接続されており,アウトバウンドHTTPS要求を行うことができ,URIとコードを表示するか別の方法でユーザに通信でき,およびユーザにパソコンやスマートフォンなどリクエストを処理することが可能な二次デバイスがあることである. OAuthクライアントとユーザエージェント間の双方向通信の必要はなく,幅広いユースケースが可能になる.

クライアントは,ユーザエージェントとインタラクションする代わりに,エンドユーザに別のコンピュータまたはデバイスを使用するように指示し,アクセス要求を承認するため認可サーバに接続させる.クライアントはリクエストを受けとることができないため,ユーザが承認プロセスを完了するまで,許可サーバに繰り返しポーリングする.

図1. デバイスフロー

図1に示すデバイスフローは,下記の通り.

(A) クライアントは,認可サーバへ,クライアント識別子を含んだアクセス要求リクエストを送る.

(B) 認可サーバは,検証コード,ユーザコードを発行し,検証URIを提供する.

(C) クライアントは,ユーザエージェント(他のもの)を使用して,提供された検証URIへアクセスさせる.クライアントは,アクセスを許可するために入力するユーザコードを提供する.

(D) 認可サーバは(ユーザエージェントを介して)エンドユーザを認証し,クライアントのアクセス要求に同意するよう促す.同意する場合,クライアントが提供するユーザコードを入力する. 認可サーバは,エンドユーザが提供するユーザコードを検証する.

(E) エンドユーザがクライアントの要求に同意(あるいは拒否)している間(ステップD),クライアントは認可サーバに繰返しポーリングし,承認ステップを完了したかどうか確認する.クライアントからのポーリングには,検証コードとクライアント識別子を含む.

(F) エンドユーザがアクセスに同意すると,認可サーバは,クライアントから提供された検証コードを検証し,アクセストークンを返却する.

2. 用語

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

デバイス認可エンドポイント(Device Authorization Endpoint)

  • 認可サーバの本エンドポイントは,デバイス検証コード,ユーザコード,および検証URLを発行する.

デバイス検証コード(Device Verification Code)

  • 認可セッションを表す有効期間の短いトークン.

ユーザコード(End-User Verification Code)

  • デバイスがエンドユーザに表示する有効期間の短いトークン.エンドユーザが認可サーバに入力し,デバイスをエンドユーザに紐付けるために使用する.

3. プロトコル

3.1. デバイス認可リクエスト

クライアントは,デバイス認可エンドポイントに対し,HTTPPOSTで検証コードのセットを要求することによってフローを開始する. クライアントは,application/x-www-form-urlencodedのコンテンツタイプでエンコードされた以下のパラメータでリクエストを構成する.

  • client_id

    • 必須(REQUIRED).

    • [RFC6749]の2.2節で定義されているクライアント識別子

  • scope

    • 任意(OPTIONAL).

    • [RFC6749]の3.3節で定義されている,アクセスを要求するスコープ

例えば,クライアントは下記のようなHTTPリクエストを作成する. (表示用に改行含む)

デバイス認可リクエスト例
POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
client_id=459691054427

値なしでパラメータが送られた場合,省略されたものとして扱わなければならない(MUST).認可サーバは認識できないパラメータは無視しなければならない(MUST).リクエスト及びレスポンスのパラメータは1回より多く含まれてはならない(MUST NOT).

3.2. デバイス認可レスポンス

認可サーバは,限られた期間のみ有効なデバイス検証コードおよびユーザコードを生成し,HTTPレスポンスボディにapplication/jsonフォーマットそれらを含め,200 OK ステータスコードでレスポンスを返却する.レスポンスには,以下のパラメータが含まれる.

  • device_code

    • 必須(REQUIRED).

    • デバイス検証コード

  • user_code

    • 必須(REQUIRED).

    • ユーザコード

  • verification_uri

    • 必須(REQUIRED).

    • 認可サーバのエンドユーザ検証URI.このURIは短く,エンドユーザがユーザエージェントに手動での入力を求められても覚えやすいものであるべき.

  • verification_uri_complete

    • 任意(OPTIONAL).

    • user_code(あるいは同じ意味を持つ他の情報)を含む,非テキスト送信用に設計された検証URI .

  • expires_in

    • 任意(OPTIONAL).

    • device_codeuser_codeの有効期間(秒).

  • interval

    • 任意(OPTIONAL).

    • トークンエンドポイントにポーリングリクエストを送る際,ここで送られた期間(秒)は最低待機しなければならない(SHOULD).

デバイス認可レスポンス例
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code":"WDJB-MJHT",
"verification_uri":"https://www.example.com/device",
"verification_uri_complete":"https://www.example.com/device?user_code=WDJB-MJHT",
"expires_in" : 1800,
"interval": 5
}

3.3. ユーザインタラクション

認可レスポンスが成功した後,クライアントはuser_codeとverification_uriをエンドユーザに表示するか別の方法で伝達し,二次デバイス上のユーザエージェント(例えば,自分の携帯のブラウザ)からURIへアクセスし,ユーザコードを入力するように指示する.

図2. ユーザインタラクションの例

ユーザをverification_uriにナビゲートし,TLSセッションにて認可サーバで認証する. 認可サーバは,デバイス認証セッションを識別するため,クライアントが提供するuser_codeを入力するように促す.続いて実行中の操作を通知し,同意または拒否するよう要求する.ユーザインタラクションが完了したら,ユーザに元のデバイスに戻るよう案内する.

ユーザインタラクション中,デバイスは,ユーザがインタラクションを完了するか,コードが期限切れになるか,別のエラーが発生するまで,3.4節で説明したようにトークンエンドポイントをdevice_codeで継続的にポーリングする.device_codeはユーザ向けのコードではないため,表示も通信もしてはいけない(MUST NOT).

この仕様をサポートする認可サーバは,ユーザをverification_uriにナビゲートすることから始まり,インタラクション中にuser_codeが提供されるシーケンスを実装しなければならない(MUST).ユーザインタラクションにおいて正確に実装しなければならないシーケンスは認可サーバまでであり,それ以上については本仕様の範囲外である.

認可サーバが検証URI(verification_uri)にユーザコードを含めることは推奨されない(NOT RECOMMENDED).それによりユーザが入力する必要があるURIの長さと複雑さが増してしまう.次項では,この情報を伝達するように設計されたverification_uri_completeを使ったユーザインタラクションについて説明する.

3.3.1. 非テキスト検証URI

3.2節の認可レスポンスにverification_uri_completeが含まれている場合,QRコードやNFCなどでブラウザを開かせてユーザが手動で入力する手間を省くため,非テキスト形式で提示することがある(MAY).

ユーザビリティ上の理由から,クライアントがそのようなショートカットを使用できないようにテキストで検証URI(verification_uri)を表示することが推奨されている(RECOMMENDED).ユーザがデバイスを混同してしまうことを避けるために認可サーバがコードを確認させる他,リモートのフィッシング対策(5.3節参照)のため,クライアントはuser_codeを表示しなければならない.

図3. QRコードを使った検証URIでのユーザインタラクション例

3.4. デバイスアクセストークンリクエスト

ユーザへの指示を表示した後,クライアントはトークンエンドポイントに対して,urn:ietf:params:oauth:grant-type:device_codegrant_typeでアクセストークン要求を行う. [RFC6749]4.5節で定義されている拡張グラントタイプであり,以下のパラメータを使用する.

  • grant_type

    • 必須(REQUIRED).

    • urn:ietf:params:oauth:grant-type:device_codeでなければならない(MUST).

  • device_code

    • 必須(REQUIRED).

    • device_codeとして3.2節で定義しているデバイス認可レスポンスから取得されるデバイス検証コード

  • client_id

    • 必須(REQUIRED).

    • [RFC6749]3.2.1項で定義されているような方法で認可サーバにより認証されていないクライアントは必須.

クライアントからのHTTPS要求例は下記の通り(改行は表示用).

デバイスアクセストークンリクエスト例
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=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
&client_id=459691054427

クライアントがクレデンシャルを発行されている,または他の認証要件が提供されている場合,クライアントは[RFC6749]3.2.1項で説明されているように,認可サーバで認証されなければならない(MUST).静的に配布されたクライアントのクレデンシャルのセキュリティへについては,5.5節を参照.

このリクエストへのレスポンスは3.5節で定義されている.OAuthの他のグラントタイプとは異なり,クライアントはレスポンスのエラーコードに基づいてアクセストークン要求をポーリングで繰返し試みる.

3.5. デバイスアクセストークンレスポンス

ユーザが同意した場合,トークンエンドポイントは[RFC6749]5.1節で定義された成功レスポンスを返却する.それ以外の場合は,[RFC6749]5.2節で定義されるようにエラーを返却する.

[RFC6749]5.2節で定義されたエラーコードに加えて,デバイスフロー特有のエラーコードは下記の通りである.

  • authorization_pending

    • 認可リクエストがまだエンドユーザとのインタラクション中で完了しておらず,3.3節の通りペンディング中である.クライアントは繰返しトークンエンドポイントへアクセストークンリクエストを送り続けるべきである.

  • slow_down

    • クライアントのポーリングが早すぎるため,適切な間隔でポーリングを行うべきである.

  • expired_token

    • device_codeの有効期限が切れている.クライアントは新しくデバイス認可リクエストからやり直す必要がある.

authorization_pendingslow_downのエラーコードはソフトエラーとみなされる.クライアントはソフトエラーを受け取ったときにデバイストークンリクエスト(3.4節)を繰返すことによってトークンエンドポイントをポーリングし続け,slow_downエラーが受信されたときにはポーリング間隔を長くするべきである.他のエラーコードはハードエラーと見なされる.クライアントはポーリングを停止し,例えばユーザにエラーを表示するなどで対応する必要がある.

検証コードが有効期限切れになっている場合,サーバはOAuthの標準エラーinvalid_grantを返却する必要がある(SHOULD).クライアントは,新しいデバイス認証セッションを開始してもよ(MAY).

クライアントのポーリング間隔は,デバイス認可レスポンス(3.2節参照)で返されるintervalパラメータよりも短くしてはならない(MUST NOT).intervalが返却されなかった場合,クライアントは合理的なデフォルトのポーリング間隔を使用しなければならない(MUST).

本仕様の前提は,ユーザーがリクエストに同意している二次デバイスからOAuthクライアントに返却する方法がないことである.本フローを多くのシナリオで役立つようにするに必要なのは,一方向チャネルのみである.たとえば,外部へのリクエストのみを行うことができるテレビ上のHTMLアプリなどである.選択されたユーザインタラクションのリターンチャネルが存在する場合,デバイスは,トークンリクエストを開始する前に,そのチャネル上でユーザがアクションを完了したことを通知されるまで待つこともできる(MAY). しかし,そのような動作についてはこの仕様の範囲外である.

4. メタデータのディスカバリ

デバイスフローをサポートしていることは,OAuth 2.0 認可サーバメタデータ[I-D.ietf-oauth-discovery]中以下のメタデータで宣言することができる.

  • device_authorization_endpoint

    • 任意(OPTIONAL).

    • 3.1節で定義されている認可サーバのデバイス認可エンドポイントURL.

5. セキュリティに関する考察

5.1. ユーザコード ブルートフォース

ユーザコードはユーザによって手動入力されるため,ユーザビリティ上の理由によりより短いコードが望ましい.これは,コード長がユーザビリティに影響を与えないデバイス検証コードや他のOAuthベアラトークンに使用されるものよりも一般的にエントロピーが少ないことを意味する.したがって,サーバはユーザーコードの試行をレート制限することを推奨する.ユーザコードは,レート制限や他の緩和と組み合わせて,ブルートフォース攻撃を実行不可能にするのに十分なエントロピーを持つべきである(SHOULD).

ユーザコードのブルートフォースが成功すると,攻撃者は自分のクレデンシャルで認証し,デバイスに認可を与えることができるようになる.これは,OAuthベアラトークンのブルートフォースとは反対のシナリオであり,これによって攻撃者はターゲットの認可制御ができるようになる.いくつかのアプリでは,この攻撃は経済的には意味がないかもしれない.たとえばビデオアプリの場合,デバイスの所有者は攻撃者のアカウントで映画を購入できるかもしれないが,この場合,プライバシーの観点での悪用を考慮しなければならない.制御を行ったアカウントで,ターゲットのデバイスを制御するなどセンシティブなアクションを実行できる可能性がある.

ユーザコードとエントロピーの適切な長さは,認可サーバの裁量に委ねられており,所有しているユーザリソースの保護必要度を考慮する必要がある.また,ユーザコードの形式を決定する際には,ユーザビリティの観点からコード長を考慮するとともに,レート制限のような攻撃耐性の観点からも考慮するべきである.

5.2. デバイスの信頼性

他のネイティブアプリのOAuth 2.0フローとは異なり,認可リクエストを行うデバイスは,ユーザがアクセスに同意したデバイスと同じではない.したがって,同意を行ったユーザのセッションおよびデバイスからの信号は,クライアントデバイスの信頼性には関係しない.

このフローで使用される認可サーバが悪意のあるサーバであった場合,バックチャネル・フローの途中で他の認可サーバに接続する可能性がある.このシナリオでは,エンドユーザが間違ったサービスの認可ページで終了するため,認可リクエストが間違っていることに気づく機会が与えられており,攻撃している中間者が完全に見えないわけではない.これを可能にするには,デバイス製造元が直接攻撃者になるか,中間者攻撃を実行するデバイスを出荷するか,デバイスが使用する認可サーバが攻撃者によって構築されているなど攻撃者に制御された認可サーバを使用する必要がある.デバイスを購入する人は,ある程度,デバイスとそのビジネスパートナーが信頼できるものと確信してしまっている

5.3. リモートフィッシング

デバイスフローは,攻撃者が所有するデバイスから開始することが可能である.たとえば攻撃者が,ターゲットに検証URLにアクセスし,ユーザーコードを入力するよう促す電子メールを送信する場合がある.そのような攻撃を緩和するため,ユーザインタラクション中(3.3節を参照)にデバイスを認可しているということをユーザに通知し,デバイスが自身の所有物であることを確認することが推奨される(RECOMENDED).認可サーバは,ソフトウェアクライアントがハードウェアデバイスを偽装しようとしていた場合それを知ることができるように,デバイスに関する情報を表示すべきである(SHOULD).

クライアントが認可URIにユーザコードを追加するために3.3.1項で指定されたオプションをサポートする認可サーバについては,ユーザが手動でコードを入力する必要がないため,ユーザがそのデバイスを所有していることを確認することが特に重要である.1つの可能性としては,認可フロー中にコードを表示し,ユーザが設定しているデバイスに同じコードが表示されることを確認するように求めることである.

ユーザコードは,有効期限を十分長くする必要がある(ユーザが2次デバイスを用意したり,検証URIやログインなどをナビゲートするのに十分な時間にする必要がある)が,フィッシングにより取得されたコードが使用されてしまうことを防ぐために十分短くする必要もある.これは,特にリアルタイムのユーザインタラクションにおいて,提示されたトークンがフィッシングされることを防ぐものではないが,電子メールやSMSで送信されるコードが使用されてしまうことを制限する.

5.4. セッションスパイ

デバイスが同意待ちになっている間に,悪意のあるユーザがデバイスのユーザインターフェイスをこっそりと調査し,そのユーザを起動したユーザよりも早く同意を完了してセッションを乗っ取る可能性がある.デバイスは,悪意のあるユーザが確認できてしまう機会を減らすために,コードをユーザに伝達する方法を検討する際,OS環境を考慮しなければならない(SHOULD).

5.5. Confidentialでないクライアント

ほとんどのデバイスはConfidentialクライアントとすることができない.複数のユーザに配布されるアプリの一部として静的に含まれるSecretはConfidentioalであるとみなされないためだ.そのようなクライアントの場合,[RFC6819]5.3.1項と[RFC8252]8.9節を適用することが推奨される.

5.6. 視覚的でないコード送付方法

デバイスによってユーザコードが視覚的に表示される必要はない.text-to-speechオーディオやBluetooth Low Energyなどの他の一方向通信も潜在的に使用できる.悪意のあるユーザが自分のクレデンシャルを自分が制御できないデバイスにブートストラップする攻撃を緩和するため,選択された通信チャネルは近接した人々のみアクセス可能とすることが推奨される(RECOMMENDED).例えば,デバイスを見たり,聞いたり,近距離無線信号の範囲内にいるユーザなど.

6. ユーザビリティの考察

本章では,ユーザビリティに関する考察を記している.

6.1. 推奨するユーザコード

多くのユーザにとって,もっとも身近なインターネットに接続されたデバイスは携帯電話であり,通常これらのデバイスでの入力はコンピュータのキーボードよりも時間がかかる.ユーザビリティを向上させる(エントリ速度を向上させて再試行を減らす)ためには,ユーザ文字セットを選択するときに文字セットの制限を考慮する必要がある.

入力速度を向上させる方法の1つは,文字セットを大文字と小文字を区別せず 数字を使わないA〜Zに制限することである.これらの文字は,通常変換キーを使用せずにモバイルキーボードから入力できる.更に,ランダムに単語が作成されるのを避けるために母音を削除すると,ベースの20文字のセットは "BCDFGHJKLMNPQRSTVWXZ" となる.読みやすいように,ダッシュやその他の句読点を含んでもよい.

このガイドラインに従った20^8のエントロピーを持つユーザコードの例が "WDJB-MJHT" である.

純粋な数値コードは,高いエントロピーを維持するために長さを長くする必要があるが,A-Z文字キーボードが使用されていないロケールをターゲットとしているクライアントでは特にユーザビリティの良い選択肢である.

10^9のエントロピーを持つ数字のユーザコードの例は "019-450-730" である.サーバは,ユーザコードの文字セットではない句読点のような文字を無視する必要がある.大文字小文字を区別する文字セットでない場合は,大文字と小文字を区別するべきではない.

6.2. 非ブラウザでのユーザインタラクション

デバイスと認可サーバは,3.3節で説明されたものに加え,代替コードを送信することでユーザインタラクションの方法をネゴシエートすることもできる(MAY).このような代替のユーザインタラクションフローは,例えば,ブルートゥースを使用して認可サーバに紐づいたアプリにコードを送信することによって,ブラウザの必要性およびコードの手動入力を不要にすることができる.そのようなインタラクション方法は,最終的に,ユーザが認可サーバにおける認可セッションを識別するだけでよいので,本プロトコルを利用することができる.ただし,検証URI以外でのユーザインタラクションは,本仕様の範囲外である.

7. IANA Considerations

7.1. OAuth URI Registration

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.1

7.1.1. Registry Contents

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.1

7.2. OAuth Extensions Error Registration

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.

7.2.1. Registry Contents

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.2.1

7.3. OAuth 2.0 Authorization Server Metadata

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.

7.3.1. Registry Contents

See original ->https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-7.3.1

8. Normative References

See original -> https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#section-8

Appendix A. Acknowledgements

See original -> https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#appendix-A

Appendix B. Document History

See original -> https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09#appendix-B

Authors' Addresses