Authorization Code Flow を使用して独自の API を呼び出す

Authorization Code Flow を使用して、通常の Web アプリケーションから独自の API を呼び出す方法を説明します。

このチュートリアルでは、Authorization Code Flow を使用して独自の API を呼び出す方法を説明します。フローの仕組みや、このフローを使用すべき理由については、Authorization Code Flowを参照してください。通常の Web アプリにログインを追加する方法については、Add Login Using the Authorization Code Flowを参照してください。

Auth0 では、アプリに 認可コード Flow を、次を使用して簡単に実装できます。

• Regular Web App Quickstarts: フローを実装する最も簡単な方法です。
• Authentication API: 独自のソリューションを構築したい場合は、このまま読み進めて API を直接呼び出す方法を確認してください。

​

前提条件

このチュートリアルを始める前に:

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

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

• Auth0 に API を登録します

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

​

手順

ユーザーの認可を行う

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

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

ユーザーを認可するには、アプリケーションからユーザーを 認可 URL に送信する必要があります。

​

認可 URL の例

パラメーター

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

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

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

たとえば、アプリケーションにログインを追加する場合の認可 URL の HTML スニペットは、次のようになります。

​

レスポンス

正常に処理されると、HTTP 302 レスポンスを受け取ります。認可コードは URL の末尾に含まれます。

HTTP/1.1 302 Found
Location: {https://yourApp/callback}?code={authorizationCode}&state=xyzABC123

トークンを取得する

認可コードを取得できたら、それをトークンと交換します。前のステップで取得した認可コード (code) を使用して、トークンURLにPOSTリクエストを送信してください。

​

トークンURLへのPOSTの例

パラメーター

パラメーター名	説明
grant_type	authorization_codeに設定します。
code	このチュートリアルの前の手順で取得したauthorization_code。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
client_secret	アプリケーションのクライアントシークレットです。この値は、Application Settings で確認できます。利用可能なアプリケーションの認証方法について詳しくは、Application Credentials を参照してください。
redirect_uri	Application Settings で設定した有効な callback 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トークンの有効期限が切れた後に、新しいトークンを取得するために使用されます。refresh_tokenがレスポンスに含まれるのは、offline_accessスコープを含め、かつDashboardでAPIのAllow Offline Accessを有効にしている場合のみです。

リフレッシュトークンは、ユーザーが実質的に半永久的に認証済みの状態を維持できるため、厳重に保管する必要があります。

API を呼び出す

通常の Web アプリケーションから 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です。アプリケーション設定で確認できます。
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トークンを検証するおよびアクセストークンを検証するを参照してください。

​

使用例

​

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

Auth0 Actions を使用すると、アクセストークンのスコープを変更したり、アクセストークンや IDトークンにカスタムクレームを追加したりできます。Actions の詳細については、Auth0 Actions の仕組みを理解する を参照してください。

これを行うには、次の Post-Login Action を追加します。これは、ユーザーの認証後に実行されます。

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');
};

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

​

詳しく見る

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