Client Credentials Exchange

Hooks を、データベース接続およびパスワードレス接続で利用できる Client Credentials Exchange 拡張ポイントで使用する方法を説明します。

ルールおよび Hooks の提供終了 (EOL) 日は 2026年11月18日 です。また、2023年10月16日 以降に作成された新規テナントでは、これらはすでに利用できません。既存のテナントで有効な Hooks を使用している場合は、提供終了まで Hooks 機能を引き続き利用できます。

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

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

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

Client Credentials Exchange 拡張ポイントでは、クライアント認証情報フローを使用して Authentication API の POST /oauth/token エンドポイント から Access Token が発行される際に、Hooks を使ってカスタムアクションを実行できます。たとえば、トークンの発行を拒否したり、Access Token にカスタムクレームを追加したり、scope を変更したりできます。詳しくは、Client Credentials Flow をご覧ください。

この拡張ポイントの Hooks はブロッキング (同期) 型です。つまり、トリガーの処理の一部として実行され、Hook が完了するまで Auth0 パイプラインの残りの処理は実行されません。

Client Credentials Exchange 拡張ポイントの triggerId は credentials-exchange です。この拡張ポイント用の Hook を作成する方法については、Create Hooks をご覧ください。

ほかの拡張ポイントについては、Extensibility Points をご覧ください。

​

スターターコードとパラメータ

Client Credentials Exchange の拡張ポイントで実行される Hook を作成する際は、以下のスターターコードが参考になります。Hook 関数に渡して利用できるパラメータは、コードサンプルの冒頭に記載されています。

/**
@param {object} client - クライアント情報
@param {string} client.name - クライアント名
@param {string} client.id - クライアント ID
@param {string} client.tenant - Auth0 テナント名
@param {object} client.metadata - クライアントメタデータ
@param {array|undefined} scope - トークンのスコープクレームを表す文字列の配列、または undefined
@param {string} audience - トークンの audience クレーム
@param {object} context - Auth0 コンテキスト情報
@param {object} context.webtask - フック（webtask）コンテキスト
@param {function} cb - function (error, accessTokenClaims)
*/

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope; // この行を削除しないでください

  // スコープを変更するか、追加のクレームを付与する
  // access_token['https://example.com/claim'] = 'bar';
  // access_token.scope.push('extra');

  // トークンを拒否して OAuth 2.0 エラーレスポンスを返す
  // if (denyExchange) {
  //   // HTTP 400 で { "error": "invalid_scope", "error_description": "Not authorized for this scope." } を返す場合
  //   return cb(new InvalidScopeError('Not authorized for this scope.'));
  //
  //   // HTTP 400 で { "error": "invalid_request", "error_description": "Not a valid request." } を返す場合
  //   return cb(new InvalidRequestError('Not a valid request.'));
  //
  //   // HTTP 500 で { "error": "server_error", "error_description": "A server error occurred." } を返す場合
  //   return cb(new ServerError('A server error occurred.'));
  // }

  cb(null, access_token);
};

以下の点にご注意ください。

• サンプルコードの末尾にあるコールバック関数 (cb) は、処理の完了を通知するためのもので、必ず含める必要があります。

• access_token.scope = scope という行は、付与されたすべてのスコープがアクセストークンに含まれるようにするためのものです。これを削除すると、すべてのスコープがリセットされ、トークンにはスクリプトで追加したスコープだけが含まれます。

​

デフォルトレスポンス

Client Credentials Exchange 拡張ポイントで Hook を実行すると、デフォルトのレスポンスオブジェクトは次のとおりです。

{
  "scope": "array of strings"
}

​

スターターコードのレスポンス

スコープと追加のクレームを使ってスターターコードをカスタマイズしたら、Hook Editor に組み込まれているランナーで Hook をテストできます。ランナーは、Client Credentials Exchange で取得されるものと同じリクエスト本文とレスポンスを使って、Hook の呼び出しをシミュレートします。

ランナーでコードを実行するには保存が必要なため、元のコードは上書きされます。

スターターコードに基づく Hook を実行すると、レスポンスオブジェクトは次のようになります。

{
  "audience": "https://my-tenant.auth0.com/api/v2/",
  "client": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "client-name",
    "tenant": "my-tenant",
    "metadata": {
      "plan": "full"
    }
  },
  "scope": [
    "read:connections"
  ]
}

​

サンプルスクリプト: アクセストークンにスコープを追加する

この例では、Hook を使用して、アクセストークンにすでに含まれているスコープに追加のスコープを加えます。

module.exports = function(client, scope, audience, context, cb) {
    // 追加するスコープ
    var access_token = {};

    // アクセストークンに現在設定されているスコープを取得し、
    // 作業中のオブジェクトに追加する
    // この行は削除しないこと！
    access_token.scope = scope;

    // `read:resource` スコープを追加する
    access_token.scope.push('read:resource');

    // 完了を通知し、新しいスコープの配列を返すコールバック
    cb(null, access_token);
};

詳しくは、スコープをご覧ください。

​

レスポンス

このHookを実行すると、レスポンスオブジェクトは次のようになります。

{
  "scope": [
    "read:connections",
    "read:resource"
  ]
}

​

サンプルスクリプト: アクセストークンにクレームを追加する

この例では、名前空間付きのカスタムクレームとその値をアクセストークンに追加します。詳細については、Create Namespaced Custom Claimsを参照してください。

発行されたトークンには、次の内容をクレームとして追加できます。

• レスポンスオブジェクトの scope プロパティ
• 名前空間付きのプロパティ名を持つ任意のプロパティ

拡張ポイントでは、レスポンスオブジェクトのそのほかのプロパティはすべて無視されます。

フック内から設定済みの Hook Secret にアクセスするには、context.webtask.secrets.SECRET_NAME を使用します。

module.exports = function(client, scope, audience, context, cb) {
    // 追加するクレーム
    var access_token = {};

    // トークンに追加する新しいクレーム
    access_token['https://example.com/foo'] = 'bar';

    // 完了を示し、新しいクレームを返すコールバック
    cb(null, access_token);
  };

​

レスポンス

このHookを実行したときのレスポンスオブジェクトは次のとおりです。

{
  "https://example.com/foo": "bar"
}

​

サンプルスクリプト: エラーを返す、またはアクセストークンを拒否する

この例では、独自の Error オブジェクトを使用して、OAuth 2.0 のエラーレスポンスを生成します。 (詳しくは、IETF Datatracker の OAuth2 RFC - セクション 5.2を参照してください。)

次のように、通常の JavaScript エラーがコールバックで返されると:

module.exports = function(client, scope, audience, context, cb) {
    // 完了を示し、新しいクレームを返すコールバック
    cb(new Error("Unknown error occurred.");
  };

その後、/oauth/token エンドポイントに client_credentials グラントをリクエストすると、Auth0 は次のように応答します：

HTTP 500
{ "error": "server_error", "error_description": "Unknown error occurred." }

ただし、OAuth 2.0 のエラーレスポンスをより細かく制御したい場合は、代わりに使用できる 3 つのカスタム Error オブジェクトが用意されています。

​

InvalidScopeError

module.exports = function(client, scope, audience, context, cb) {
    const invalidScope = ...; // スコープが有効かどうかを確認する

    if(invalidScope) {
      cb(new InvalidScopeError("Scope is not permitted."));
    }
  };

続いて、/oauth/token エンドポイントに client_credentials グラントをリクエストすると、Auth0 は次のように応答します：

HTTP 400
{ "error": "invalid_scope", "error_description": "Scope is not permitted." }

​

InvalidRequestError

module.exports = function(client, scope, audience, context, cb) {
    const invalidRequest = ...; // リクエストが有効かどうかを確認する

    if(invalidRequest) {
      cb(new InvalidRequestError("Bad request."));
    }
  };

その後、/oauth/token エンドポイントに client_credentials グラントをリクエストすると、Auth0 からは次のような応答が返されます。

HTTP 400
{ "error": "invalid_request", "error_description": "Bad request." }

​

ServerError

module.exports = function(client, scope, audience, context, cb) {
    callOtherService(function(err, response) {
      if(err) {
        return cb(new ServerError("Error calling remote system: " + err.message));
      }
    });
  };

次に、/oauth/token エンドポイントに対して client_credentials グラントをリクエストすると、Auth0 は次のように応答します：

HTTP 400
{ "error": "server_error", "error_description": "Error calling remote system: ..." }

現時点では、組み込みの JavaScript Error クラスと ServerError の動作は同じですが、ServerError クラスを使うと、返される OAuth 2.0 エラーを明示的に指定できます。

​

さらに詳しく