Skip to main content

デバイスフローの有効化

はじめに

いわゆる「デバイスフロー」は、Web ブラウザ非搭載のデバイスや、文字入力が困難なデバイスが API クライアントとなる場合に、ユーザーの承認に基づいてアクセストークンを発行する認可フローです。RFC 8628 (OAuth 2.0 Device Authorization Grant) によって定義されています。 本記事では、Authlete を用いたデバイスフロー対応認可サーバーの構成と、Authlete の設定手順について説明します。
本機能は Authlete バージョン 2.1 以降にて利用可能です。

Authlete API を用いた認可サーバーのデバイスフロー対応

認可サーバーがデバイスフローに対応するためには、以下のエンドポイントおよび「検証 URI」の、新設・改修が必要です。これらを実装するための機能を、Authlete は API として提供しています。 enabling-device-flow_1

Authlete の設定

本セクションではデバイスフローに対応するための設定を説明します。Authlete サービスと、同フローを用いるクライアントの、両方の設定が必要です。

Authlete サービスの設定

管理者コンソールから以下の項目を設定します。 enabling-device-flow_2 enabling-device-flow_3

クライアントの設定

クライアントアプリ開発者コンソールにアクセスし、以下の項目を設定します。
本記事では、デバイスは「コンフィデンシャルではないクライアント 」を想定しています。もしデバイスがコンフィデンシャルクライアントである場合には、「クライアントタイプ」および「クライアント認証方式」についてそれぞれ適切な値を選択してください。
enabling-device-flow_4 enabling-device-flow_5 enabling-device-flow_6

実行例

以下は、クライアントからのデバイス認可リクエストを起点に、エンドユーザーから提示された user_code の検証を行い、クライアントからのトークンリクエストに対して応答する例です。 device-flow-2_ja

デバイス認可リクエスト

ここでは、クライアントが認可サーバーに対して以下の「デバイス認可リクエスト」を送信したとします(手順 #2)。(以下の例はいずれも、読みやすさのために折り返しています)
認可サーバーは Authlete の /device/authorization にこのリクエストの内容を転送し、処理を依頼します(手順 #3, 4)。
  • リクエスト(手順 #3。curl コマンドによる実行例)
  • レスポンス(手順 #4)
認可サーバーは Authlete から返却された “responseContent” を、デバイス認可レスポンスの内容として、クライアントに返却します(手順 #5。詳細は省略)。

「検証 URI」

user_code の検証

クライアントは、認可サーバーから返却されたレスポンスに含まれる “device_code” の値を用いて、認可サーバーに対し、「デバイスアクセストークンリクエスト」を送信します(後述)。 その一方、同じくレスポンスから取得した “user_code” の値を、認可サーバーの「検証 URI」に提示するよう、エンドユーザーに促します(手順 #6)。 どのように提示するかはクライアントに任されています。以下は、先のレスポンスに含まれる “verification_uri” の値と共に、エンドユーザーに示す例 (RFC 8628 の例 に加筆) です。
また以下は、同じくレスポンスに含まれる “verification_uri_complete” の値を QR コードにエンコードし、エンドユーザーにスキャンしてもらう例 (RFC 8628 の例 に加筆) です。
なんらかの方法でエンドユーザーから user_code を受け取った認可サーバーの「検証 URI」では(手順 #7)、Authlete の /device/verification API に user_code を転送し、処理を依頼します(手順 #8, 9)。
  • リクエスト(手順 #8。curl コマンドによる実行例)
  • レスポンス(手順 #9)
このレスポンスには、user_code の値の検証に成功したことの他に、アクセストークンを要求しているクライアントの情報や、どのようなスコープやクレームを求めているかといった情報が含まれています。 認可サーバーはこれらをもとに、エンドユーザーに同意確認を行うことになります。

検証完了

必要に応じて認可サーバーは、エンドユーザーを認証し、上記の情報から「どのクライアントがどのようなアクセス権を要求しているか」をエンドユーザーに提示します(手順 #10, 11)。 そしてエンドユーザーのユーザー識別子と、発行するトークンのプロパティ(スコープやクレームなど)が確定した段階で、Authlete の /device/complete API を呼び出し、処理を依頼します(手順 #12, 13)。
  • リクエスト(手順 #12。curl コマンドによる実行例)
  • レスポンス(手順 #13)
この後認可サーバーは処理が完了した旨をエンドユーザーに示し、検証処理を終了します(手順 #14)。

トークンリクエスト

前述の通りクライアントは、 “device_code” の値を用いて、認可サーバーに対し「デバイスアクセストークンリクエスト」を送信します(手順 #a)。基本的には、user_code の検証が完了してアクセストークンが取得できるまで、繰り返しリクエストを行います(ポーリングします)。
  • リクエスト(手順 #b。curl コマンドによる実行例)
  • レスポンス(手順 #c。user_code の検証完了前)
  • レスポンス(手順 #c。user_code の検証完了後)
認可サーバーは “responseContent” の値を抽出し、クライアントに返却します(手順 #d)。

関連情報