Hooks を使用して Client Credentials フローのトークンをカスタマイズする

Hooks を使用して、Client Credentials フローで取得するアクセストークンのスコープを変更し、カスタムクレームを追加する方法を学びます。

Rules と Hooks のサポート終了 (EOL) 日は 2026年11月18日 です。2023年10月16日 以降に作成された新規テナントでは、これらはすでに利用できません。既存のテナントでアクティブな Hooks がある場合は、サポート終了日まで Hooks へのアクセスが維持されます。

Auth0 を拡張するには、Actions の使用を強く推奨します。Actions では、豊富な型情報、インラインドキュメント、公開 npm パッケージを利用でき、拡張機能の活用体験を向上させる外部統合にも接続できます。Actions の機能の詳細については、Understand How Auth0 Actions Work を参照してください。

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

Rules と Hooks の廃止の詳細については、ブログ記事 Preparing for Rules and Hooks End of Life を参照してください。

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

Rules を Actions に移行する方法については、Migrate from Rules to Actions を参照してください。Hooks を Actions に移行する方法については、Migrate from Hooks to Actions を参照してください。

Client Credentials フロー を通じて発行されるトークンでは、Hooks を追加することで、スコープを変更したり、カスタムクレームを追加したりできます。

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

Hooks は、Auth0 Dashboard または Management API を使用して管理できます。

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

​

前提条件

このチュートリアルを開始する前に、次の作業を行ってください。

• Auth0 に API を登録する

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

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

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

​

手順

1. Hook を作成: トークンをカスタマイズする Hook を作成します。
2. Hook をテスト: Client Credentials フローを実行し、アクセストークンをデコードして、新しい 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 Exchange を実行して アクセストークン を取得し、それをデコードして内容を確認する必要があります。

​

トークンを取得する

トークンを取得するには、Client Credentials Flow エンドポイント に POST リクエストを送信します。CLIENT_ID、CLIENT_SECRET、API_IDENTIFIER のプレースホルダー値は、それぞれアプリケーションの クライアントID、アプリケーションの クライアントシークレット、および API の識別子に置き換えてください。クライアントID とクライアントシークレットは Application の設定で、API の識別子は API の設定で確認できます。

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

• access_token
• 有効期限 (秒単位、expires_in)
• Bearer に設定されたトークンタイプ (token_type)
• extra 権限 (scope、Hook によって追加)

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
• Client Credentials フロー
• Client Credentials フローで API を呼び出す