Hybrid Flow を使用して API を呼び出す

アプリでHybrid Flowを実行して、IDトークンを使ってユーザー情報にアクセスしつつ、アクセストークンと交換できる認可コードを取得する方法を説明します。

このチュートリアルでは、Hybrid Flow を使用して独自の API を呼び出す方法を説明します。フローの仕組みや Hybrid Flow を使用すべき理由については、Hybrid Flowを参照してください。

Auth0 を使用すると、次の方法でアプリに Authorization Code Flow を簡単に実装できます。

• Authentication API: 独自のソリューションを構築したい場合は、このまま読み進めて、API を直接呼び出す方法を確認してください。

​

前提条件

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

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

  • 適切な Application Type を選択します。
  • Allowed Callback URL に {https://yourApp/callback} を追加します。
  • アプリケーションの Grant Types に Implicit と 認可コード が含まれていることを確認します。手順については、Update Grant Types を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにするには、アプリケーションの Grant Types に Refresh Token が含まれていることを確認します。手順については、Update Grant Types を参照してください。リフレッシュトークンの詳細については、Refresh Tokens を参照してください。

• Auth0 に API を登録する

  • 以前のトークンの有効期限が切れたときに API が新しいトークンを取得できるよう、API でリフレッシュトークンを受け取れるようにする場合は、Allow Offline Access を有効にします。

​

手順

1. ユーザーを認可: ユーザーに認可を求め、認可コードとともにアプリにリダイレクトします。
2. トークンをリクエスト: 認可コードをトークンと交換します。
3. API を呼び出す: 取得したアクセストークンを使用して API を呼び出します。
4. トークンを更新: 既存のトークンの有効期限が切れたら、リフレッシュトークンを使用して新しいトークンをリクエストします。

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

​

ユーザーを認可する

この手順には、次のプロセスのうち 1 つ以上が含まれる場合があります。

• ユーザーを認証する
• 認証を処理するため、ユーザーを IDプロバイダー にリダイレクトする
• 有効な シングルサインオン (SSO) セッションを確認する
• 以前に同意が与えられていない場合は、要求された権限レベルに対するユーザーの同意を取得する。

ユーザーを認可するには、アプリでユーザーを 認可 URL に送信する必要があります。

​

認可 URL の例

パラメーター

カスタム API の呼び出し時にユーザーを認可する場合は、次の点に注意してください。

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

パラメーター名	説明
response_type	Auth0 が返す認証情報の種類 (code または token) を示します。このフローでは、値に code を含める必要がありますが、id_token、token、または id_token token を含めることもできます。具体的には、id_token は IDトークン を返し、token は アクセストークン を返します。
response_mode	レスポンスパラメーターの返却方法を指定します。セキュリティ上の理由から、値は form_post にする必要があります。このモードでは、レスポンスパラメーターは HTML フォームの値としてエンコードされ、HTTP POST メソッドで送信され、リクエスト本文では application/x-www-form-urlencoded 形式でエンコードされます。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
redirect_uri	ユーザーが認可すると、Auth0 がブラウザーをリダイレクトする URL です。認可コード は code URL パラメーターで取得できます。この URL は、Application Settings で有効な callback URL として指定する必要があります。 警告: OAuth 2.0 Specification に従い、Auth0 はハッシュ以降のすべてを削除し、フラグメントは 一切考慮しません。
scope	認可をリクエストする スコープ を指定します。これにより、返されるクレーム (またはユーザー属性) が決まります。これらはスペース区切りで指定する必要があります。profile や email など、ユーザーに関する 標準 OpenID Connect (OIDC) スコープ、名前空間付き形式 に準拠した カスタムクレーム、または対象 API がサポートする任意のスコープ (例: read:contacts) をリクエストできます。リフレッシュトークン を取得するには offline_access を含めてください (Application Settings で Allow Offline Access フィールドが有効になっていることを確認してください) 。
audience	アプリケーションがアクセスする API の一意の識別子です。このチュートリアルの前提条件の一部として作成した API の Settings タブにある Identifier の値を使用します。
state	(推奨) アプリが初期リクエストに追加する、不透明な任意の英数字文字列です。Auth0 は、アプリケーションにリダイレクトする際にこの値を含めます。この値を使ってクロスサイトリクエストフォージェリ (CSRF) 攻撃を防ぐ方法については、Mitigate CSRF Attacks With State Parameters を参照してください。
nonce	アプリが初期リクエストに追加し、Auth0 が IDトークン に含める暗号学的にランダムな文字列です。トークンのリプレイ攻撃を防ぐために使用されます。
organization	(任意) ユーザーの認証時に使用する組織の ID です。指定しない場合、アプリケーションで Display Organization Prompt が設定されていれば、ユーザーは認証時に組織名を入力できます。
invitation	(任意) 組織への招待の ticket ID です。組織にメンバーを招待する 場合、ユーザーが招待を承諾した際に、アプリケーションは invitation と organization のキーと値の組を転送して、招待の承諾を処理する必要があります。

例として、アプリにログインを追加する際の認可 URL 用 HTML スニペットは次のようになります。

​

レスポンス

正常に処理されると、HTTP 302 レスポンスが返されます。要求した認証情報はレスポンス本文にエンコードされています。

HTTP/1.1 302 Found
Content-Type: application/x-www-form-urlencoded
code=AUTHORIZATION_CODE&
access_token=ey...MhPw
&expires_in=7200
&token_type=Bearer
id_token=eyJ...acA&
state=xyzABC123

返される値は、response_type として何をリクエストしたかによって異なることに注意してください。

Response Type	Components
code	認可コード
id_token	IDトークン
token	アクセストークン (expires_in と token_type の値を含む)
id_token token	IDトークン、アクセストークン (expires_in と token_type の値を含む)

Auth0 は、認可 URL の呼び出しに含めた state の値も返します。

このトランザクションで受け取るアクセストークンは、最初に返されるアクセストークンにすぎません。これを API の呼び出しに使用することは推奨されません。

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

IDトークン をデコードして解析すると、c_hash という追加の claim が含まれていることがわかります。これは code のハッシュを含む claim です。この claim は、IDトークンが code と同時に発行される場合に必須であり、検証する必要があります。

1. IDトークンヘッダーの alg claim で指定されたハッシュアルゴリズムを使用して、code の ASCII 表現のオクテットをハッシュ化します。
2. ハッシュの左半分を Base64url エンコードします。
3. 結果が c_hash の値と一致することを確認します。

​

トークンを取得する

認可コードを取得したら、それをトークンと交換する必要があります。前の手順で取得した認可コード (code) を使用して、トークンURL に POST します。

この手順で受け取るアクセストークンは、API の呼び出しに使用するものです。このチュートリアルの前の手順で受け取ったアクセストークンとは、必ず別に管理してください。

​

トークンURLにPOSTする例

パラメーター

Parameter Name	Description
grant_type	authorization_code に設定します。
code	このチュートリアルの前の手順で取得した authorization_code です。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
client_secret	アプリケーションのクライアントシークレットです。この値は Application Settings で確認できます。使用可能なアプリケーションの認証方法の詳細については、Application Credentials を参照してください。
redirect_uri	Application Settings で設定した有効なコールバック URL です。この値は、このチュートリアルの前の手順で認可 URL に渡した redirect_uri と完全に一致している必要があります。なお、URL エンコードされている必要があります。

​

レスポンス

正常に処理されると、access_token、refresh_token、id_token、token_type の各値を含むペイロードを伴う HTTP 200 レスポンスが返されます。

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

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

IDトークンには、デコードして取り出す必要があるユーザー情報が含まれています。

アクセストークンは、Auth0 Authentication API の /userinfo エンドポイントまたは別の API を呼び出すために使用されます。独自の API を呼び出す場合、API で最初に行う必要があるのは、アクセストークンを検証することです。

リフレッシュトークンは、前のアクセストークンまたは IDトークン の有効期限が切れたあとに、新しいアクセストークンまたは IDトークン を取得するために使用されます。refresh_token がレスポンスに含まれるのは、offline_access スコープを指定し、Dashboard で API の Allow Offline Access を有効にした場合のみです。

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

​

API を呼び出す

通常の Web アプリケーション (または、アプリケーションの認証情報を安全に保存できる同様のケース) から API を呼び出すには、取得したアクセストークンを Bearer トークンとして HTTP リクエストの Authorization ヘッダーで渡す必要があります。

​

リフレッシュトークン

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

• オフラインアクセスを許可するように API を設定した
• authorize エンドポイント を通じて認証リクエストを開始する際に、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 で確認できます。
refresh_token	使用するリフレッシュトークンです。
scope	(任意) 要求するスコープ権限をスペース区切りで指定したリストです。指定しない場合は元のスコープが使用されます。指定した場合は、スコープを絞って要求できます。なお、URL エンコードが必要です。

​

レスポンス

正常に処理されると、新しい access_token、その有効期間 (秒単位、expires_in) 、付与された scope の値、および token_type を含むペイロードを伴う HTTP 200 レスポンスが返されます。初期トークンのスコープに openid が含まれている場合、レスポンスには新しい id_token も含まれます。

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

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

​

ユースケースの例

​

トークンのカスタマイズ

Rules を使用すると、返されるアクセストークンのスコープを変更したり、アクセストークンや IDトークンにクレームを追加したりできます。 (Rules の詳細については、Auth0 Rulesを参照してください。) これを行うには、以下の Rule を追加します。この Rule は、ユーザーの認証後に実行されます。

exports.onExecutePostLogin = async (event, api) => {
  // アクセストークンとIDトークンにカスタムクレームを追加する
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // アクセストークンのスコープを変更する
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

すべての Rules の実行が完了すると、トークンでスコープを利用できるようになります。

Auth0 は、OpenID Connect (OIDC) specification で定義されている構造化クレーム形式でユーザープロファイル情報を返します。つまり、IDトークンまたはアクセストークンに追加するカスタムクレームは、競合の可能性を避けるためにガイドラインと制限事項に準拠している必要があります。

​

詳細情報

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