Device Authorization Flow を使用して API を呼び出す

Device Authorization Flow を使用して、入力が制限されたデバイスから API を呼び出す方法を学びます。

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

Auth0 を使えば、アプリに Device Authorization フロー を簡単に実装できます。

• Authentication API: Auth0 の API を直接呼び出す方法については、このまま読み進めてください。対話形式で試したい場合は、Device Flow Playgroundを参照してください。

​

前提条件

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

• Device Authorization Flow が実装に適していることを確認するため、制限事項 (下記) を確認します。

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

  • アプリケーションの種類 として Native を選択します。
  • 必要に応じて Allowed Web Origins を設定します。これは、ローカル開発用に localhost をオリジンとして許可したり、CORS の対象となる特定の TV ソフトウェア (例: HTML5 + JS) に対して許可するオリジンを設定したりする場合に使用できます。ほとんどのアプリケーションでは、この設定は使用しません。
  • OIDC Conformant トグルが有効になっていることを確認します。この設定は、Auth0 Dashboard の アプリケーション > アプリケーション > 詳細設定 > OAuth にあります。
  • アプリケーションの グラントタイプ に デバイスコード が含まれていることを確認します。方法については、グラントタイプを更新する を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにするには、アプリケーションの グラントタイプ に リフレッシュトークン が含まれていることを確認します。方法については、グラントタイプを更新する を参照してください。リフレッシュトークンの詳細については、リフレッシュトークン を参照してください。

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

• Auth0 に API を登録します

  • API が以前のトークンの有効期限が切れたときに新しいトークンを取得できるよう、API でリフレッシュトークンを受け取れるようにするには、オフラインアクセスの許可 を有効にします。リフレッシュトークンの詳細については、リフレッシュトークン を参照してください。

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

​

手順

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

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

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

​

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

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

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

​

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

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

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

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

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

パラメーター名	説明
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
scope	認可をリクエストする スコープ です。スペース区切りで指定する必要があります。profile や email などのユーザーに関する 標準 OIDC スコープ、名前空間形式 に準拠した カスタムクレーム、または 対象 API でサポートされている任意のスコープ (例: read:contacts) をリクエストできます。ID トークンを取得する場合、またはユーザーのプロファイル情報を取得するために /userinfo endpoint を使用できるようにする場合は、openid を含めてください。リフレッシュトークンを取得するには、offline_access を含めてください (API 設定 で オフラインアクセスの許可 フィールドが有効になっていることを確認してください) 。なお、これは URL エンコードする必要があります。
audience	アプリがアクセスする API の一意の識別子です。このチュートリアルの前提条件として作成した API の 設定 タブにある 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が含まれます。これにより、必要に応じてアプリで user_code をURLに埋め込めます。
• expires_in は、device_code と user_code の有効期間 (秒) を示します。
• interval は、token URL に対して token をリクエストするためにアプリがポーリングを行う間隔 (秒) を示します。

ランダムに生成される user code の文字セット、形式、長さは、テナント設定で構成できます。

ブルートフォース攻撃を防ぐため、user_code には次の制限を設けています。

最小長:

• BASE20 Letters: 8文字
• Numbers: 9文字

最大長:

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

有効期限:

• 15分

​

デバイスのアクティベーションをリクエストする

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

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

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

​

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

ユーザーがデバイスを有効化するのを待つ間に、アクセストークン をリクエストするため、token URL へのポーリングを開始します。前のステップで取得したポーリング間隔 (interval) を使って、device_code を含めたうえで token URL に POST する必要があります。

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

​

token URL に token をリクエストする POST の例

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

パラメータ名	説明
grant_type	これを “urn:ietf:params:oauth:grant-type:device_code” に設定します。これは拡張グラントタイプです (RFC6749 の第4.5節で定義されています) 。なお、これは URL エンコードする必要があります。
device_code	このチュートリアルの前のステップで取得した device_code です。
client_id	お使いのアプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。

​

トークン応答

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

認可保留中

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

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": "..."
}

これは、たとえば次のようなさまざまな理由で発生することがあります。

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

​

ユーザーを認可する

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

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

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

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

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

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

​

トークンを受け取る

ユーザーがデバイスの認証と認可を行っている間も、デバイスアプリはアクセストークンを要求するために Token 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 を呼び出すために使用されます。 (アクセストークンの詳細については、Access Tokens を参照してください。) アクセストークンで /userinfo を呼び出せるのは、openid scope を含めた場合のみです。独自の API を呼び出す場合、最初に必要になるのは アクセストークンを検証する ことです。

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

リフレッシュトークン は、以前のアクセストークンまたは ID トークンの有効期限が切れたあとに、新しいアクセストークンまたは ID トークンを取得するために使用されます。 (リフレッシュトークンの詳細については、Refresh Tokens を参照してください。) refresh_token がレスポンスに含まれるのは、offline_access scope を含め、さらに Auth0 Dashboard でその API に対して オフラインアクセスの許可 を有効にしている場合のみです。

リフレッシュトークンがあれば、ユーザーの認証状態を実質的に無期限で維持できるため、安全に保管する必要があります。

​

API を呼び出す

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

​

リフレッシュトークン

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

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

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

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

​

Token URL へのリフレッシュトークンの POST の例

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

パラメーター名	説明
grant_type	これを “refresh_token” に設定します。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
client_secret	アプリケーションの Client Secret です。この値は アプリケーション設定 で確認できます。
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 トークンを検証する と アクセストークンを検証する をご覧ください。

​

使用例

​

Device Authorization Flow の使用を検出する

ルールを使用すると、現在のトランザクションで Device Authorization Flow が使われているかどうかを検出できます。 (ルールの詳細については、Auth0 ルール を参照してください。) その場合は、context オブジェクトの protocol プロパティを確認します。

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

​

サンプル実装

• Device Authorization Playground
• AppleTV (Swift): AppleTV で Device Authorization Flow を使用して Auth0 を利用する方法を示すシンプルなアプリケーションです。
• CLI (Node.js): 認可コードフローではなく Device Authorization Flow を使用する CLI のサンプル実装です。主な違いは、CLI で Web サーバーを立ち上げてポートを待ち受ける必要がないことです。

​

トラブルシューティング

テナントログは、発生したあらゆる操作について作成され、問題の切り分けに利用できます。詳しくは、ログを参照してください。

​

エラーコード

Code	Name	Description
fdeaz	デバイス認可リクエストの失敗
fdeac	デバイスのアクティブ化の失敗
fdecc	ユーザーがデバイスの確認をキャンセルしました
fede	交換に失敗	デバイスコードをアクセストークンに交換
sede	交換に成功	デバイスコードをアクセストークンに交換

​

制限事項

Device Authorization Flow を使用するには、デバイスが次の要件を満たしている必要があります。

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

さらに、Device Authorization Flow では次のことはサポートされていません。

• Universal Login エクスペリエンスを使用している場合を除き、Auth0 developer keys を使用する Social Connections
• ホストされたログインページ、ルール、または Actions からクエリ文字列パラメーターにアクセスすること
• ユーザーアカウントのリンク

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

​

詳細はこちら

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