デバイス認可フローを使用して API を呼び出す

入力が制限されたデバイスからデバイス認可フローを使用して API を呼び出す方法を学びます。

このチュートリアルでは、デバイス認可フローを使用して、入力機能が制限されたデバイスから独自のAPIを呼び出す方法を説明します。このフローの仕組みや、これを使用すべき理由について詳しくは、デバイス認可フローを参照してください。

Auth0 を使用すると、アプリにデバイス 認可フローを簡単に実装できます。使用するものは次のとおりです。

• Authentication API: API を直接呼び出す方法については、このまま読み進めてください。インタラクティブに試すには、デバイスフロー・プレイグラウンドを参照してください。

​

前提条件

このチュートリアルを始める前に、以下を確認してください。

• 制限事項 (以下) を確認し、デバイス認可フローが実装に適していることを確認してください。

• アプリケーションを Auth0 に登録します。

  • Application Type で Native を選択します。
  • 必要に応じて、Allowed Web Origins を設定します。これは、ローカル開発時に localhost をオリジンとして許可したり、CORS の制約を受けるアーキテクチャの特定の TV ソフトウェア (例: HTML5 + JS) に対して許可するオリジンを設定したりするために使用できます。ほとんどのアプリケーションでは、この設定は不要です。
  • OIDC 準拠 トグルが有効になっていることを確認します。この設定は、Dashboard の Applications > Application > Advanced Settings > OAuth にあります。
  • アプリケーションの Grant Types に Device Code が含まれていることを確認します。手順については、Update Grant Types を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにする場合は、アプリケーションの Grant Types に Refresh Token が含まれていることを確認します。手順については、Update Grant Types を参照してください。リフレッシュトークンの詳細については、Refresh Tokens を参照してください。

• アプリケーションに対して少なくとも 1 つの接続を設定し、有効にします: データベース接続, ソーシャル接続

• API を Auth0 に登録します

  • API が以前のトークンの有効期限が切れた際に新しいトークンを取得できるよう、リフレッシュトークンを受け取れるようにしたい場合は、Allow Offline Access を有効にします。リフレッシュトークンの詳細については、Refresh Tokens を参照してください。

• デバイスユーザーコード設定を構成します。これにより、ランダムに生成されるユーザーコードの文字セット、形式、長さを定義できます。

​

手順

1. デバイスコードをリクエストする (デバイスフロー) : ユーザーがデバイスを認可する際に使用するデバイスコードをリクエストします。
2. デバイスのアクティベーションをリクエストする (デバイスフロー) : ユーザーに、ラップトップまたはスマートフォンを使用してデバイスを認可するよう求めます。
3. トークンをリクエストする (デバイスフロー) : トークンを取得するために、トークンエンドポイントをポーリングします。
4. ユーザーを認可する (ブラウザフロー) : ユーザーがデバイスを認可し、デバイスがトークンを受け取れるようにします。
5. トークンを受け取る (デバイスフロー) : ユーザーがデバイスの認可に成功すると、トークンを受け取ります。
6. API を呼び出す (デバイスフロー) : 取得したアクセストークンを使用して API を呼び出します。
7. トークンを更新する (デバイスフロー) : 既存のトークンの有効期限が切れたら、リフレッシュトークンを使用して新しいトークンをリクエストします。

任意: サンプルユースケースを確認する。

任意: トラブルシューティング。

​

デバイスコードをリクエストする

ユーザーがデバイスアプリを起動してそのデバイスを認可しようとする場合は、デバイスコードを取得する必要があります。ユーザーがブラウザーでセッションを開始すると、このコードはそのセッションに関連付けられます。

デバイスコードを取得するには、アプリから device code URL に対して code をリクエストする必要があります。その際、クライアントID を含めます。

​

デバイスコード URL への POST の例

デバイスコードのパラメーター

カスタム API を呼び出すためにデバイスコードをリクエストする場合は、次の点に注意してください。

• audience パラメーターを含める必要があります
• 対象 API でサポートされている追加のスコープを含めることができます

認証済みユーザーの情報を取得するためだけにアプリでアクセストークンが必要な場合は、audience パラメーターは不要です。

パラメーター名	説明
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
scope	認可をリクエストする スコープ です。各値はスペースで区切る必要があります。profile や email などのユーザーに関する 標準 OIDC スコープ、名前空間形式 に準拠した カスタムクレーム、または 対象 API でサポートされている任意のスコープ (例: read:contacts) をリクエストできます。IDトークンを取得する場合、またはユーザーのユーザープロファイル情報を取得するために /userinfo エンドポイント を使用できるようにする場合は、openid を含めてください。リフレッシュトークンを取得するには、offline_access を含めます (API Settings で Allow Offline Access フィールドが有効になっていることを確認してください) 。この値は URL エンコードする必要があります。
audience	アプリがアクセスする API の一意の識別子です。このチュートリアルの前提条件として作成した API の Settings タブにある Identifier の値を使用してください。この値は URL エンコードする必要があります。

​

デバイスコードのレスポンス

正常に処理されると、device_code、user_code、verification_uri、expires_in、interval、verification_uri_complete の各値を含むペイロードを含む HTTP 200 レスポンスを受け取ります。

{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://accounts.acmetest.org/activate",
  "verification_uri_complete": "https://accounts.acmetest.org/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}

• device_code はデバイス固有のコードです。ユーザーがブラウザーを利用できるデバイスで verification_uri にアクセスすると、このコードがそのセッションに紐付けられます。
• user_code には、デバイスを認可するために verification_uri で入力するコードが含まれます。
• verification_uri には、デバイスを認可するためにユーザーがアクセスするURLが含まれます。
• verification_uri_complete には、デバイスを認可するためにユーザーがアクセスする完全なURLが含まれます。これにより、必要に応じてアプリでURLに user_code を埋め込めます。
• expires_in は、device_code と user_code の有効期間 (秒) を示します。
• interval は、トークンをリクエストするためにアプリがトークンURLをポーリングする間隔 (秒) を示します。

テナント設定では、ランダムに生成されるユーザーコードの文字セット、形式、長さを設定できます。

総当たり攻撃を防ぐため、user_code には次の制限が適用されます。

最小長:

• BASE20 の文字: 8 文字
• 数字: 9 文字

最大長:

• 20 文字 (読みやすくするための区切りとして追加されるハイフンとスペースを含む)

有効期限:

• 15 分

​

デバイスのアクティベーションを依頼する

device_code と user_code を受け取ったら、ユーザーにノートパソコンまたはスマートフォンで verification_uri にアクセスし、user_code を入力するよう案内する必要があります。

device_code はユーザーが直接使用するものではないため、混乱を避けるために、この操作中は表示しないでください。

CLI を構築している場合は、この手順を省略し、すぐに verification_uri_complete でブラウザーを開くこともできます。

​

トークンをリクエストする

ユーザーがデバイスを有効化するのを待っている間に、アクセストークンを取得するため、トークンURLのポーリングを開始します。前の手順で取得したポーリング間隔 (interval) を使用して、device_code を送信し、トークンURL に POST する必要があります。

ネットワーク遅延によるエラーを避けるため、各間隔の計測は、直前のポーリングリクエストへのレスポンスを受信してから開始してください。

​

トークンURLに対してトークンをリクエストするPOSTの例

トークンリクエストのパラメーター

パラメーター名	説明
grant_type	これを “urn:ietf:params:oauth:grant-type:device_code” に設定します。これは拡張グラントタイプです (RFC6749 のセクション 4.5 で定義) 。なお、URL エンコードが必要です。
device_code	このチュートリアルの前の手順で取得した device_code です。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。

​

トークンのレスポンス

ユーザーがデバイスを認可するまでの間、HTTP 4xx 応答がいくつか返されることがあります。

認可保留中

このエラーは、ユーザーの操作を待っている間に表示されます。このチュートリアルの前の手順で取得した推奨間隔で、ポーリングを続けてください。

HTTP/1.1 403 Forbidden
{
  "error": "authorization_pending",
  "error_description": "..."
}

間隔を空けてください

ポーリングの間隔が短すぎます。このチュートリアルの前の手順で取得した推奨間隔を使用してください。ネットワーク遅延が原因でこのエラーが発生するのを防ぐには、各間隔の計測を、直前のポーリングリクエストへのレスポンスを受信した後に開始する必要があります。

HTTP/1.1 429 Too Many Requests
{
  "error": "slow_down",
  "error_description": "..."
}

期限切れのトークン

ユーザーがデバイスをすみやかに承認しなかったため、device_code の有効期限が切れています。アプリケーションは、フローの有効期限が切れたことをユーザーに通知し、フローを開始し直すよう促す必要があります。

expired_token エラーは 1 回だけ返され、その後は invalid_grant が返されます。デバイスは必ずポーリングを停止する必要があります。

HTTP/1.1 403 Bad Request
{ 
  "error": "expired_token",
  "error_description": "..."
}

アクセス拒否

最後に、アクセスが拒否された場合は、次の内容が返されます。

HTTP/1.1 403 Forbidden
{
  "error": "access_denied",
  "error_description": "..."
}

これは、以下のようなさまざまな理由で発生することがあります。

• ユーザーがデバイスの認可を拒否した
• 認可サーバーがトランザクションを拒否した
• 設定された Rule によってアクセスが拒否された (詳しくは、Auth0 Rules を参照してください。)

​

ユーザーを認可する

ユーザーは、QRコードをスキャンするか、アクティベーションページを開いてユーザーコードを入力します。

正しいデバイスであることをユーザーに確認してもらうため、確認ページが表示されます。

ユーザーはサインインしてトランザクションを完了します。この手順には、次のプロセスの 1 つ以上が含まれる場合があります。

• ユーザーの認証
• 認証を処理するための、ユーザーの IDプロバイダー へのリダイレクト
• アクティブな SSO セッションの確認
• 以前に同意が与えられていない場合の、デバイスに対するユーザー同意の取得

認証と同意が正常に完了すると、確認プロンプトが表示されます。

この時点で、ユーザーの認証が完了し、デバイスの認可も完了しています。

​

トークンの受信

ユーザーがデバイスの認証と認可を行っている間も、デバイスアプリはアクセストークンを要求するためにトークンURLへのポーリングを継続します。

ユーザーがデバイスを正常に認可すると、access_token、refresh_token (省略可能) 、id_token (省略可能) 、token_type、expires_in の各値を含むペイロードを伴う HTTP 200 レスポンスを受信します。

{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

保存する前に、トークンを検証してください。方法については、IDトークンを検証する および アクセストークンを検証する を参照してください。

アクセストークンは、Auth0 Authentication API の /userinfo エンドポイント または別の API を呼び出すために使用します。 (アクセストークンの詳細については、アクセストークン を参照してください。) openid スコープを含めた場合にのみ、アクセストークンを使用して /userinfo を呼び出せます。独自の API を呼び出す場合、最初に行う必要があるのは、API で アクセストークンを検証する ことです。

IDトークン には、デコードして取り出す必要があるユーザー情報が含まれています。 (IDトークンの詳細については、IDトークン を参照してください。) id_token は、openid スコープを含めた場合にのみレスポンスに含まれます。

リフレッシュトークン は、以前のアクセストークンまたは IDトークン の有効期限が切れた後に、新しいアクセストークンまたは IDトークン を取得するために使用されます。 (リフレッシュトークンの詳細については、リフレッシュトークン を参照してください。) refresh_token は、offline_access スコープを含め、Dashboard で API の Allow Offline Access を有効にした場合にのみレスポンスに含まれます。

リフレッシュトークンを使うと、ユーザーを実質的に無期限に認証済みの状態に保てるため、安全に保管する必要があります。

​

API を呼び出す

API を呼び出すには、HTTP リクエストの Authorization ヘッダーに、取得したアクセストークンを Bearer トークンとして含める必要があります。

​

リフレッシュトークン

このチュートリアルに沿って進め、次の項目を完了していれば、すでにリフレッシュトークンを受け取っています。

• オフラインアクセスを許可するように API を設定した
• 認可エンドポイント を介して認証リクエストを開始する際に、offline_access スコープを含めた

リフレッシュトークンを使用すると、新しいアクセストークンを取得できます。通常、ユーザーが新しいアクセストークンを必要とするのは、以前のアクセストークンの有効期限が切れた場合か、新しいリソースに初めてアクセスする場合だけです。API を呼び出すたびに新しいアクセストークンを取得するためにエンドポイントを呼び出すのは推奨されません。また、Auth0 ではレート制限が設けられており、同じ IP から同じトークンを使用してそのエンドポイントに送信できるリクエスト数は制限されます。

トークンを更新するには、grant_type=refresh_token を使用して、Authentication API の /oauth/token エンドポイントに POST リクエストを送信します。

​

トークンURLにリフレッシュトークンをPOSTする例

リフレッシュトークンのリクエストパラメーター

パラメーター名	説明
grant_type	"refresh_token" に設定します。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
client_secret	アプリケーションのクライアントシークレットです。この値は Application Settings で確認できます。
refresh_token	使用するリフレッシュトークンです。
scope	(任意) 要求するスコープのスペース区切りリストです。送信しない場合は元のスコープが使用されます。送信した場合は、より限定されたスコープのセットを要求できます。なお、URL エンコードが必要です。

​

リフレッシュトークンのレスポンス

正常に処理されると、新しい access_token、id_token (省略可) 、トークンの有効期間 (秒) (expires_in) 、付与された scope 値、および token_type を含むペイロードとともに、HTTP 200 レスポンスが返されます。

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

保存する前に、トークンを検証してください。方法については、IDトークンの検証およびアクセストークンの検証を参照してください。

​

使用例

​

デバイス認可フローの使用を検出する

Rules を使用すると、現在のトランザクションでデバイス認可フローが使われているかどうかを検出できます。 (Rules の詳細については、Auth0 Rules を参照してください。) これを行うには、context オブジェクトの protocol プロパティを確認します。

function (user, context, callback) {
   if (context.protocol === 'oauth2-device-code') {
      ...
   }
 
   callback(null, user, context);
}

​

サンプル実装

• デバイス認可プレイグラウンド
• AppleTV (Swift): AppleTV でデバイス認可フローを使用して Auth0 を利用する方法を示すシンプルなアプリケーションです。
• CLI (Node.js): Authorization Code Flow の代わりにデバイス認可フローを使用する CLI のサンプル実装です。主な違いは、CLI では Web サーバーをホストしてポートで待ち受ける必要がないことです。

​

トラブルシューティング

テナントログは、発生したあらゆる操作に対して作成され、問題のトラブルシューティングに利用できます。詳細については、Logsを参照してください。

​

エラーコード

Code	名前	説明
fdeaz	デバイス認可リクエストの失敗
fdeac	デバイス有効化の失敗
fdecc	ユーザーによるデバイス確認のキャンセル
fede	交換の失敗	デバイスコードをアクセストークンに交換
sede	交換の成功	デバイスコードをアクセストークンに交換

​

制限事項

デバイス認可フローを使用するには、デバイスが以下の条件を満たしている必要があります。

• カスタムドメイン を使用する場合は、Server Name Indication (SNI) をサポートしていること
• Auth0 application type が Native であること
• Token Endpoint Authentication Method が None に設定されていること
• OIDC-conformant であること
• Dynamic Client Registration で作成されていないこと

さらに、デバイス認可フローでは以下はサポートされません。

• Universal Login experience を使用している場合を除き、Auth0 developer keys を使用する ソーシャル接続
• ホスト型ログインページ、Rules、または Actions からのクエリ文字列パラメーターへのアクセス
• ユーザーアカウントのリンク

confidential Clients を除き、Draft 15 全体をサポートしています。詳しくは、ietf.org の OAuth 2.0 Device Authorization Grant Draft 15 を参照してください。

​

詳細情報

• OAuth 2.0 認可フレームワーク
• OpenID Connect プロトコル
• トークン
• ログ