ハイブリッドフロー を使って API を呼び出す

ハイブリッドフロー を実行し、アプリが ID トークンを使ってユーザー情報にアクセスすると同時に、アクセストークンと交換可能な認可コードを取得する方法を学びます。

このチュートリアルでは、ハイブリッドフローを使用して独自のAPIを呼び出す方法を説明します。このフローの仕組みや、使用する理由について詳しく知りたい場合は、ハイブリッドフローを参照してください。

Auth0 を使うと、次の方法でアプリに認可コードフローを簡単に実装できます。

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

​

前提条件

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

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

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

• Auth0 に API を登録する

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

​

手順

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

任意: サンプルのユースケースを見る

​

ユーザーを認可する

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

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

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

​

認可 URL の例

パラメータ

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

• audience パラメータを含める必要があります
• 対象 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	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
redirect_uri	ユーザーが認可を許可した後に、Auth0 がブラウザーをリダイレクトする URL です。認可コードは code URL パラメータで取得できます。この URL は、アプリケーション設定 で有効な callback URL として指定する必要があります。 警告: OAuth 2.0 仕様 に従い、Auth0 はハッシュ以降のすべてを削除し、フラグメントは無視されます。
scope	認可をリクエストする スコープ を指定します。これは、返してほしいクレーム (またはユーザー属性) を決定します。各値はスペースで区切る必要があります。profile や email など、ユーザーに関する 標準 OpenID Connect (OIDC) スコープ、名前空間付き形式 に準拠した カスタムクレーム、または対象 API がサポートする任意のスコープ (例: read:contacts) をリクエストできます。リフレッシュトークン を取得するには offline_access を含めます (アプリケーション設定 で オフラインアクセスの許可 フィールドが有効になっていることを確認してください) 。
audience	アプリケーションがアクセスしたい API の一意の識別子です。このチュートリアルの前提条件の一部として作成した API の 設定 タブにある Identifier の値を使用します。
state	(推奨) アプリが最初のリクエストに追加し、アプリケーションへリダイレクトして戻る際に Auth0 が含める、不透明な任意の英数字文字列です。この値を使ってクロスサイトリクエストフォージェリ (CSRF) 攻撃を防ぐ方法については、Mitigate CSRF Attacks With State Parameters を参照してください。
nonce	アプリが最初のリクエストに追加し、Auth0 が ID トークン内に含める、暗号学的にランダムな文字列です。トークンリプレイ攻撃の防止に使用されます。
organization	(任意) ユーザーの認証時に使用する organization の ID です。指定しない場合、アプリケーションで Display Organization Prompt が設定されていれば、ユーザーは認証時に organization名 を入力できます。
invitation	(任意) organization 招待の ticket ID です。Organizations にメンバーを招待する 場合、ユーザーが招待を承諾した際に、アプリケーションは invitation と organization のキーと値のペアを転送して招待承諾を処理する必要があります。

例として、アプリに login を追加する際の認可 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 の値を含む)

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

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

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

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

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

​

トークンを取得する

認可コードを取得したら、次はそれをトークンに交換する必要があります。前のステップで取得した認可コード (code) を使って、トークン URL に POST します。

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

​

token URL に POST する例

パラメーター

パラメーター名	説明
grant_type	authorization_code に設定します。
code	このチュートリアルの前の手順で取得した authorization_code です。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
client_secret	アプリケーションの Client Secret です。この値は アプリケーション設定 で確認できます。利用可能なアプリケーションの認証方法について詳しくは、Application Credentials を参照してください。
redirect_uri	アプリケーション設定に設定した有効なコールバック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 スコープを含め、Auth0 Dashboard で API の オフラインアクセスの許可 を有効にしている場合のみです。

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

​

API を呼び出す

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

​

リフレッシュトークン

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

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

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

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

​

Token URL に POST する例

パラメーター

Parameter Name	Description
grant_type	refresh_token に設定します。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
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 トークンを検証する と アクセストークンを検証する を参照してください。

​

使用例

​

トークンをカスタマイズする

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

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

  // Access Token のスコープを変更する
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

スコープは、すべてのルールの実行が完了した後にトークンで利用できるようになります。

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

​

詳細情報

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