デバイスフローとは

RFC 8628 (OAuth 2.0 Device Authorization Grant) は、2019 年 8 月に Proposed Standard になった仕様です。 Web ブラウザ非搭載のデバイスや、文字入力が困難なデバイスが API クライアントとなる場合に、ユーザーの承認に基づいてアクセストークンを発行する認可フロー（デバイスフロー）を定義しています。

デバイスフローの動作

デバイスフローでは以下の状態を前提としています。

• ユーザー: Web ブラウザの使える端末（例: PC、スマートフォン、タブレットなど）を利用可能
• クライアント: インターネットにアウトバウンド接続可能なデバイス（例: TV、家電など）
• 認可サーバー: 「デバイス認可エンドポイント (Device Authorization Endpoint)」をクライアントに公開するサービス（例: 動画配信サービスなど）

フローの概要は以下の通りです。

1. **クライアント（デバイス）**は、認可サーバーの「デバイス認可エンドポイント」に、「デバイス認可リクエスト」を送信します。
2. 認可サーバーは「デバイス認可レスポンス」をクライアントに返却します。このレスポンスには主要なパラメーターとして以下が含まれます。
   • user_code: ユーザーを経由して認可サーバーに提示されます。
   • device_code: クライアントがトークンリクエストを行う際に使用します。
3. クライアントは user_code をユーザーに提示します。
4. 以下の処理が並行して行われます。
   • クライアントは認可サーバーのトークンエンドポイントに対し、device_code を含むトークンリクエストを行います。これは基本的にはトークン（あるいはエラー）が返却されるまでポーリングすることになります。
   • ユーザーは Web ブラウザを用いて認可サーバーにアクセスし、ユーザー認証と user_code の入力を行った上で、クライアントに対するアクセス付与を許可します。
5. 認可サーバーは user_code の検証を行い、その user_code に対応する device_code を含むトークンリクエストへのトークンレスポンスとして、アクセストークンを発行します。

以上のフローによってクライアントはアクセストークンを取得し、以降の API アクセスを行うことになります。

Authlete のデバイスフロー対応

Authlete はバージョン 2.1 以降でデバイスフローをサポートしています。 このバージョンにて新規追加・機能拡張された以下の Authlete API を活用し、デバイスフローに対応した認可サーバーをシンプルに実装可能です。

• /device/authorization API (新規)
  • デバイス認可リクエストを処理します。認可サーバーは、クライアントから受信した「デバイス認可リクエスト」を基本的にほぼそのままこの API リクエストの値として送信します。 Authlete はその内容を検証し、user_code や device_code を含む「デバイス認可レスポンス」の内容を生成して、認可サーバーに返却します。
• /device/verification API (新規)
  • user_code を検証します。
• /device/complete API (新規)
  • デバイス認可フローの承認・否認を処理します。その処理結果が /auth/token API のレスポンスに作用します。
• /auth/token API (機能拡張)
  • トークンリクエストを処理します。 grant_type=urn:ietf:params:oauth:grant-type:device_code と、同グラントタイプにおける device_code に対応する機能が拡張されています。

デバイスフローの処理の設定はサービス管理者コンソールから行います。

詳細情報

• 図解デバイスフロー（RFC 8628）
  • デバイスフローの仕様と Authlete の実装・利用方法についての詳説です。
• Authlete API リファレンス
  • Authlete が提供する Web API の仕様です。
• java-oauth-server
  • Authlete API を用いて実装された認可サーバーの参照実装です。Authlete がオープンソースとして公開しています。デバイスフローにも対応しています。
• JavaDoc of authlete-java-common
  • 上記の Authlete API の詳細仕様については、authlete-java-common ライブラリ の JavaDoc のうち、Device で始まるクラス群の説明を参照してください。
• シーケンス図テンプレート
  • Authlete を含む OAuth 2.0 / OIDC (OpenID Connect) フローのシーケンス図を描くためのテンプレート集です。 Authlete を用いた OAuth 2.0 デバイス認可グラントフローのシーケンス図が含まれています。