認可コードフローを使用して独自のAPIを呼び出す

認可コードフローを使用して、従来型のWebアプリから独自のAPIを呼び出す方法を学びます。

このチュートリアルでは、認可コードフローを使用して独自のAPIを呼び出す方法を紹介します。このフローの仕組みや、これを使用すべき理由について知りたい場合は、認可コードフローを参照してください。通常のWebアプリにログインを追加する方法を知りたい場合は、認可コードフローを使用してログインを追加するを参照してください。

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

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

​

事前準備

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

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

  • アプリケーションの種類 で Regular Web Apps を選択します。
  • Allowed Callback URL に {https://yourApp/callback} を追加します。
  • アプリケーションの グラントタイプ に 認可コード が含まれていることを確認します。設定方法については、グラントタイプ を更新するを参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにする場合は、アプリケーションの グラントタイプ に リフレッシュトークン が含まれていることを確認します。設定方法については、グラントタイプ を更新するを参照してください。リフレッシュトークンの詳細については、refresh tokensを参照してください。

• Auth0 に API を登録する

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

​

ステップ

ユーザーを承認する

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

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

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

​

認可 URL の例

パラメータ

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

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

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

例として、アプリに login を追加する際の認可 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	お使いのアプリケーションの Client ID です。この値は Application Settings で確認できます。
client_secret	アプリケーションの Client Secret。この値は Application Settings で確認できます。アプリケーションで利用可能な認証方法について詳しくは、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トークンの有効期限が切れた後に新しいトークンを取得するために使用されます。refresh_token がレスポンスに含まれるのは、offline_access スコープを含め、ダッシュボードでAPIのオフラインアクセスを許可を有効にした場合のみです。

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

APIを呼び出す

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

リフレッシュトークンを交換する

このチュートリアルに沿って以下の手順を完了している場合は、すでにリフレッシュトークンを取得済みです。

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

リフレッシュトークンを使用して、新しいアクセストークンを取得できます。通常、新しいアクセストークンが必要になるのは、以前のトークンの有効期限が切れた場合や、新しいリソースに初めてアクセスする場合に限られます。APIを呼び出すたびに新しいアクセストークンを取得するためにエンドポイントを呼ぶのは推奨されません。Auth0は、同じIPおよび同じトークンを使用してエンドポイントに送信できるリクエスト数に対してレート制限を設けており、その量を制限します。

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

トークン URL への POST の例

パラメータ

パラメーター名	説明
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 トークンを検証する と アクセストークンを検証する をご覧ください。

​

使用例

​

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

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 プロトコル
• トークン