> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# デバイスフロー (OAuth 2.0 Device Authorization Grant)

> 「デバイスフロー」に関する技術情報です。

<Info>
  For **Authlete 2.x** documentation, see [2.x version](/v2/configuration-reference/endpoints/enabling-device-flow).
</Info>

# デバイスフローとは

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

# デバイスフローの動作

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

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

<img src="https://mintcdn.com/authlete/WGQFc11Y4wUplGrc/protocols-and-flows/advanced-flows/device_flow_01_ja.png?fit=max&auto=format&n=WGQFc11Y4wUplGrc&q=85&s=9508878ca1fdf0a659a3159f97dd1a5d" alt="" width="1200" height="712" data-path="protocols-and-flows/advanced-flows/device_flow_01_ja.png" />

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

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 以降でデバイスフローをサポート](https://docs.authlete.com/#device-flow)しています。
このバージョンにて新規追加・機能拡張された以下の Authlete API を活用し、デバイスフローに対応した認可サーバーをシンプルに実装可能です。

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

<img src="https://mintcdn.com/authlete/WGQFc11Y4wUplGrc/protocols-and-flows/advanced-flows/device_flow_02_ja.png?fit=max&auto=format&n=WGQFc11Y4wUplGrc&q=85&s=7fcdf42915c017b3c80ea932edc9b946" alt="" width="1468" height="646" data-path="protocols-and-flows/advanced-flows/device_flow_02_ja.png" />

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

<img src="https://mintcdn.com/authlete/WGQFc11Y4wUplGrc/protocols-and-flows/advanced-flows/device_flow_03_ja.png?fit=max&auto=format&n=WGQFc11Y4wUplGrc&q=85&s=f59fdb0b437aba706604a55ec2052937" alt="" width="829" height="424" data-path="protocols-and-flows/advanced-flows/device_flow_03_ja.png" />

# 詳細情報

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