デバイス認可フロー

このチュートリアルでは、デバイス認可フローを使用して、入力に制約のあるデバイスからAPIを呼び出す方法について説明します。

このチュートリアルでは、デバイス認可フローを使用して、入力に制約のあるデバイスからAPIを呼び出す方法について説明します。 ログインして、アカウント用に構成された例を参考にこのクイックタートに従うことをお勧めします。対話型のエクスペリエンスには、Device Flow Playgroundを使用することができます。

前提条件

• ネイティブアプリケーションを登録する。

• OIDC準拠 のトグルが有効になっていることを確認する。詳細については、「OIDC準拠の認証」をお読みください。

• アプリケーションの付与タイプにデバイスコード を追加する。詳細については、「付与タイプを更新する」をお読みください。

• リフレッシュトークンを有効にしたい場合には、アプリケーションの付与タイプにリフレッシュトークン を追加する。

• アプリケーションに少なくとも1つの接続を構成して有効化する。

• APIをAuth0に登録する。

  • リフレッシュトークンを使用している場合には、［Allow Offline Access（オフラインアクセスの許可）］ を有効にする。詳細については、「APIの設定」をお読みください。

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

デバイスコードを要求する

ユーザーがデバイスアプリケーションを起動して、それを認可したい場合には、アプリケーションがAuth0 Authentication APIからのデバイスコードを要求して、ユーザーのセッションに関連付けなければなりません。

デバイスコードを取得するには、アプリケーションがAuthentication APIのデバイス認可フローで認証エンドポイントを呼び出す必要があります：

cURL

curl --request post \
  --url 'https://dev-gja8kxz4ndtex3rq.us.auth0.com/oauth/device/code' \
  --header 'content-type: application/x-www-form-urlencoded'

デバイスコードを受け取る

デバイスアプリケーションはHTTP 200応答と次のようなペイロードを受け取るはずです：

{
"device_code": "GmRh...k9eS",
"user_code": "WDJB-MJHT",
"verification_uri": "https://my-tenant.auth0.com/device",
"verification_uri_complete": "https://my-tenant.auth0.com/device?user_code=WDJB-MJHT",
"expires_in": 900,
"interval": 5
}

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

デバイスアプリケーションは、device_codeとuser_codeの受信後に、ユーザーにverification_uriでuser_codeを入力するよう指示する必要があります。

device_codeはユーザーに直接提供するものではないため、ユーザーが混乱しないように、処理中に表示するべきではありません。

CLIをビルドする際は、この手順をスキップし、verification_uri_completeを使って直接ブラウザーを開くことができます。

トークンエンドポイントをポーリングする

ユーザーによるアクティベーションを待っている間、デバイスアプリケーションはAuthentication API POST /oauth/tokenエンドポイントを断続的に呼び出して、応答を適切に処理する必要があります。

デバイスアプリケーションが確実にそのinterval（秒単位）または成功応答の受信で長い方の時間を待機して、ネットワーク遅延の問題を回避するようにします。

curl --request POST \
--url 'https://{yourDomain}/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=urn:ietf:params:oauth:grant-type:device_code \
--data device_code=AUTH0_SCOPES \
--data 'client_id={yourClientId}'

ユーザーの認可

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

確認ページが表示され、ユーザーが正しいデバイスであることを確認します：

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

• ユーザーを認証する
• 認証を行うために、ユーザーをIDプロバイダーへリダイレクトする
• アクティブなSSOセッションを確認する
• デバイスに関してユーザーの同意がまだ得られていない場合には、同意を得る

認証と同意が成功すると、確認のプロンプトが表示されます：

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

トークンを受け取る

ユーザーがデバイスアプリケーションを認可すると、HTTP 200応答と次のペイロードを受け取ります：

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

トークンは検証してから保存します。方法については、「アクセストークンを検証する 」と「IDトークンを検証する 」をお読みください。

アクセストークンは、Authentication APIのユーザー情報取得エンドポイント（デバイスアプリケーションがopenidスコープを要求した場合）、またはaudienceパラメーターが指定したAPIを呼び出すために使用されます。独自のAPIを呼び出す場合には、デバイスアプリケーションは使用する前にアクセストークンを検証しなければなりません。

IDトークンには、デコードと抽出が必要なユーザー情報が含まれています。デバイスアプリケーションがopenidスコープを要求した場合には、Authentication APIはid_tokenのみを返します。

リフレッシュトークンは、アクセストークンまたはIDトークンの期限が切れたときに、新しいトークンの取得に使用されます。audienceパラメーターが指定するAPIに**［Allow Offline Access（オフラインアクセスの許可）］** 設定が有効化されていて、デバイスアプリケーションがoffline_accessスコープを要求した場合には、Authentication APIはrefresh_tokenのみを返します。

APIを呼び出す

APIを呼び出すには、デバイスアプリケーションはアクセストークンをベアラートークンとしてHTTP要求のAuthorizationヘッダーで渡さなければなりません。

curl --request GET \
--url https://myapi.com/api \
--header 'authorization: Bearer AUTH0_API_ACCESS_TOKEN' \
--header 'content-type: application/json'

リフレッシュトークン

ユーザーに新しいアクセストークンを取得するために、デバイスアプリケーションは、refresh_tokenパラメーターを指定してAuthentication API POST /oauth/tokenエンドポイントを呼び出すことができます。

curl --request POST \
--url 'https://{yourDomain}/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=refresh_token \
--data 'client_id={yourClientId}' \
--data 'client_secret={yourClientSecret}' \
--data refresh_token=AUTH0_REFRESH_TOKEN

要求が成功すると、デバイスアプリケーションはHTTP 200応答で次のペイロードを受け取ります：

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

リフレッシュトークンの詳細については、「リフレッシュトークン」をお読みください。

トラブルシューティング

テナントログは実行されるあらゆるやり取りを記録し、問題の解決に利用することができます。

**コード**	**名前**	**説明**
fdeaz	デバイス認可要求の失敗
fdeac	デバイスのアクティベーションに失敗
fdecc	ユーザーがデバイス確認をキャンセル
fede	交換の失敗	アクセストークンのデバイスコード
sede	交換の成功	アクセストークンのデバイスコード

​

トークンの応答

ユーザーによるデバイスの認可を待っている間には、さまざまなHTTP 4xx応答を受け取ります。

​

認可待ち

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

`HTTP 403`
{
"error": "authorization_pending",
"error_description": "..."
}

​

減速

ポーリングが速すぎます。このチュートリアルの前の手順で推奨されている間隔を使ってポーリングしてください。ネットワーク遅延が原因でこのエラーを受け取ることを避けるには、ポーリング要求の応答を受け取ってから間隔をカウントし始めるようにします。

`HTTP 429`
{
"error": "slow_down",
"error_description": "..."
}

​

有効期限切れのトークン

ユーザーによるデバイスの認可が遅かったため、device_codeの期限が切れました。アプリケーションはユーザーにフローの失効を通知して、フローをもう一度始めるように促す必要があります。

expired_tokenエラーは一度だけ返されます。それ以降は、エンドポイントがinvalid_grantエラーを返します。

`HTTP 403`
{
"error": "expired_token",
"error_description": "..."
}

​

アクセス拒否

アクセスが拒否された場合には、次を受け取ります：

`HTTP 403`
{
"error": "access_denied",
"error_description": "..."
}

これは、以下を含むさまざまな原因で発生します。

• ユーザーがデバイスの認可を拒否した。
• 認可サーバーがトランザクションを拒否した。
• 構成済みのアクションがアクセスを拒否した。

実装例

以下の例を参考に、このフローを実際のアプリケーションに実装する方法を確認してください。

• Device Authorization Playground
• AppleTV（Swift）：AppleTVからのデバイス認可フローにAuth0を使用する方法を示す簡素なアプリケーションです。
• CLI（Node.js）：認可コードフローではなく、デバイス認可フローを使用するCLIの実装例です。大きな違いは、CLIがWebサーバーのホスティングやポートの待ち受けを必要としないことです。

制限事項

デバイス認可フローを使用するには、デバイスアプリケーションに以下が必要です。

• Server Name Indication（SNI）に対応している
• ネイティブアプリケーション
• 認証方法が**［None（なし）］** に設定されている
• OIDCに準拠
• 動的クライアント登録（Dynamic Client Registration）

また、デバイス認可フローには以下を使用できません：

• Auth0の開発者キーを使用したソーシャル接続（新しいユニバーサルログインエクスペリエンス
• ホストされたログインページやアクションからクエリ文字列パラメーターへのアクセス

​

次のステップ

成功です！ここまで来れば、アプリケーションにログイン、ログアウト、ユーザープロファイル情報が備わっているはずです。

これでクイックスタートチュートリアルは終了ですが、機能はまだまだたくさんあります。Auth0でできることについて詳しくは、以下をご覧ください。

• Auth0 Dashboard - Auth0のテナントやアプリケーションを構成して管理する方法について説明します

• Auth0 Marketplace - Auth0の機能性を拡張できる各種の統合を見つけられます