クライアント認証情報フローで Hooks を使用してトークンをカスタマイズする

クライアント認証情報フローで取得したアクセストークンのスコープを変更し、カスタムクレームを追加するために Hooks を使用する方法を学びます。

ルールと Hooks の提供終了 (EOL) は 2026年11月18日 で、2023年10月16日 以降に作成された新しいテナントでは、すでに利用できません。アクティブな Hooks がある既存のテナントでは、提供終了まで Hooks 製品を引き続き利用できます。

Auth0 を拡張するには、Actions の使用を強くおすすめします。Actions では、豊富な型情報、インラインドキュメント、公開 npm パッケージを利用できるほか、外部連携を接続して拡張機能の利用体験をさらに向上させることもできます。Actions でできることについて詳しくは、Understand How Auth0 Actions Work をご覧ください。

移行を支援するために、ルールから Actions への移行 と Hooks から Actions への移行 のガイドを用意しています。また、機能比較、Actions のデモ、そのほか移行に役立つリソースを紹介した専用の Move to Actions ページもあります。

ルールと Hooks の非推奨化について詳しくは、ブログ記事「Preparing for Rules and Hooks End of Life」をご覧ください。

2026 年にルールと Hooks の機能を削除する予定のため、新しいルールや Hooks を作成する場合は、Development 環境で Actions への移行をテストする目的に限ってください。

ルールを Actions に移行する方法については、Migrate from Rules to Actions をご覧ください。Hooks を Actions に移行する方法については、Migrate from Hooks to Actions をご覧ください。

クライアント認証情報フロー で発行されるトークンでは、Hooks を追加することで、スコープを変更したりカスタムクレームを追加したりできます。

Hooks を使うと、Node.js コードで Auth0 の動作をカスタマイズできます。Hooks は、Auth0 プラットフォームの特定の拡張ポイント (クライアント認証情報フローなど) に関連付けられた、安全で自己完結型の関数です。Auth0 は実行時に Hooks を呼び出し、カスタムロジックを実行します。

Hooks は、Auth0 Dashboard または Management API で管理できます。

特定の拡張ポイントに対して複数のフックを作成できますが、各拡張ポイントで一度に有効にできるフックは 1 つだけです。その拡張ポイントに対してあとから作成したフックは自動的に無効になるため、明示的に有効にする必要があります。有効になっているフックは、すべてのアプリケーションと API に対して実行されます。

​

前提条件

このチュートリアルを始める前に、次の作業を行っておく必要があります。

• Auth0 に API を登録する

  • 適切な API 権限を追加する

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

  • Application Type で Machine to Machine Applications を選択します。
  • あらかじめ登録した API を選択します。
  • M2M アプリケーションに API の呼び出しを許可します。

​

手順

1. Hook を作成: トークンをカスタマイズする Hook を作成します。
2. Hook をテスト: クライアント認証情報フローを実行し、アクセストークンをデコードして新しい Hook をテストします。

​

Hook を作成する

この例では、次のことを行います。

• アクセストークンに任意のクレーム (https://foo.com/claim) を追加する
• 設定済みの API に権限を 1 つ追加する

トークンをカスタマイズするための Hook を作成します。拡張ポイントの選択を求められたら、Client Credentials Exchange を選択し、エディターに次のコードを追加します。

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token['https://foo.com/claim'] = 'bar';
  access_token.scope = scope;
  access_token.scope.push('extra');
  cb(null, access_token);
};

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

​

フック をテストする

作成した フック をテストするには、Client Credentials 交換を実行してアクセストークンを取得し、それをデコードして内容を確認する必要があります。

​

トークンを取得する

トークンを取得するには、クライアント認証情報フローのエンドポイントに POST リクエストを送信します。CLIENT_ID、CLIENT_SECRET、API_IDENTIFIER のプレースホルダー値は、それぞれご利用のアプリケーションの Client ID、ご利用のアプリケーションの Client Secret、および API の Identifier に必ず置き換えてください。Client ID と Client Secret は アプリケーション の設定で、API Identifier は API の設定で確認できます。

成功すると、レスポンスには次のものが含まれます:

• access_token
• 有効期限 (秒単位、expires_in)
• Bearer に設定されたトークンの種類 (token_type)
• 追加の権限 extra (scope) (これはご利用のHooksによって追加されたものです)

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5ESTFNa05DTVRGQlJrVTRORVF6UXpFMk1qZEVNVVEzT1VORk5ESTVSVU5GUXpnM1FrRTFNdyJ9.eyJpc3MiOiJodHRwczovL2RlbW8tYWNjb3VudC5hdXRoMC3jb20vIiwic3ViIjoic0FRSlFpQmYxREw0c2lqSVZCb2pFRUZvcmRoa0o4WUNAY2xpZW50cyIsImF1ZCI6ImRlbW8tYWNjb3VudC5hcGkiLCJleHAiOjE0ODc3NjU8NjYsImlhdCI6MTQ4NzY3OTI2Niwic2NvcGUiOiJyZWFkOmRhdGEgZXh0cmEiLCJodHRwczovL2Zvby5jb20vY2xhaW0iOiKoPXIifQ.da-48mHY_7esfLZpvHWWL8sIH1j_2mUYAB49c-B472lCdsNFvpaLoq6OKQyhnqk9_aW_Xhfkusos3FECTrLFvf-qwQK70QtwbkbVye_IuPSTAYdQ2T-XTzGDm9Nmmy5Iwl9rNYLxVs2OoCdfpVMyda0OaI0AfHBgEdKWluTP67OOnV_dF3KpuwtK3dPKWTCo2j9VCa7X1I4h0CNuM79DHhY2wO7sL8WBej7BSNA3N2TUsp_YTWWfrvsr_vVhJf-32G7w_12ms_PNFUwj2C30ZZIPWc-uEkDztyMLdI-lu9q9TLrLdr0dOhfrtfkdeJx4pUSiHdJHf42kg7UAVK6JcA",
  "expires_in": 86400,
  "scope": "extra",
  "token_type": "Bearer"
}

​

トークンをデコードする

アクセストークンをデコードして内容を確認する最も簡単な方法は、JWT.io Debugger を使用することです。

アクセストークンをコピーしてエディターに貼り付けます。JWT は自動的にデコードされ、その内容が表示されます。

ペイロード の最後の 2 項目は、どちらもフックによって設定されていることに注目してください。

• "scope": "extra"
• "https://foo.com/claim": "bar"

​

さらに詳しく

• Auth0 Hooks
• クライアント認証情報フロー
• クライアント認証情報フローを使用して API を呼び出す