Client Credentials Exchange

データベース接続およびパスワードレス接続に利用可能なClient Credentials Exchange（クライアント資格情報交換）拡張ポイントでフックを使用する方法を説明します。

RulesとHooksのサポート終了（EOL）日は2026年11月18日 であり、2023年10月16 日の時点で作成された新しいテナントは使用できなくなります。Hooksが有効な既存のテナントは、サポート終了までHooksを利用できます。

今後はActionsに移行して、Auth0の機能を拡張することを強くお勧めします。Actionsを使用すると、豊富な情報やインラインドキュメント、パブリックnpmパッケージにアクセスして、外部統合を使って全体的な拡張エクスペリエンスを強化することができます。Actionsの詳細については、「Auth0 Actionsの仕組みを理解する」をお読みください。

当社では、移行の参考資料として、RulesからActionsへの移行とHooksからActionsへの移行に関するガイドを提供しています。また、専用の「Actionsへの移行」ページでは、機能の比較やActionsのデモ、その他のリソースを掲載して、円滑な移行をサポートしています。

RulesとHooksの廃止の詳細については、当社のブログ記事「RulesとHooksの提供終了について」をお読みください。

Client Credentials Exchange（クライアント資格情報交換）拡張ポイントでは、フックにより、クライアントの資格情報フローを使用して認証APIのPOST /oauth/tokenエンドポイントからアクセストークンが発行される際にカスタムアクションを実行できます。たとえば、トークンが発行されないように拒否する、アクセストークンにカスタムクレームを追加する、またはそのスコープを修正することができます。詳細については、「クライアントの資格情報フロー」をお読みください。

この拡張ポイントでのフックはブロッキング（同期的）であり、トリガーのプロセスの一部として実行されます。そのため、フックが完了するまでAuth0パイプラインの他の部分の実行が停止されます。

Client Credentials Exchange（クライアント資格情報交換）拡張ポイントのtriggerIdは、credentials-exchangeです。この拡張ポイントに対してフックを作成する方法については、「フックを作成する」をお読みください。

​

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

Client Credentials Exchange（クライアント資格情報交換）拡張ポイントで実行されるフックを作成する際、以下のスターターコードが役立つかもしれません。Hook関数に渡され、使用されることができるパラメーターは、コード例の最上部にリストされています。

/**
@param {object} client - client information
@param {string} client.name - client name
@param {string} client.id - client ID
@param {string} client.tenant - Auth0 tenant name
@param {object} client.metadata - client metadata
@param {array|undefined} scope - either an array of strings representing the token's scope claim, or undefined
@param {string} audience - token's audience claim
@param {object} context - Auth0 context info
@param {object} context.webtask - Hook (webtask) context
@param {function} cb - function (error, accessTokenClaims)
*/

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope; // do not remove this line

  // Modify scopes or add extra claims
  // access_token['https://example.com/claim'] = 'bar';
  // access_token.scope.push('extra');

  // Deny the token and respond with an OAuth2 error response
  // if (denyExchange) {
  //   // To return an HTTP 400 with { "error": "invalid_scope", "error_description": "Not authorized for this scope." }
  //   return cb(new InvalidScopeError('Not authorized for this scope.'));
  //
  //   // To return an HTTP 400 with { "error": "invalid_request", "error_description": "Not a valid request." }
  //   return cb(new InvalidRequestError('Not a valid request.'));
  //
  //   // To return an HTTP 500 with { "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（クライアント資格情報交換）拡張ポイントでフックを実行すると、デフォルトの応答オブジェクトは次のようになります。

{
  "scope": "array of strings"
}

​

スターターコードの応答

スコープと追加クレームを使用してスターターコードをカスタマイズしたら、Hookエディタに埋め込まれたランナーを使用してフックをテストできます。ランナーは、Client Credentials Exchange（クライアント資格情報交換）で得られるものと同じ要求ボディと応答を使ってフックへの呼び出しをシミュレートします。

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

スターターコードに基づいたフックを実行する場合、応答オブジェクトは以下の通りになります。

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

​

スクリプト例：アクセストークンに追加スコープを追加する

この例では、既存のスコープに加えてアクセストークンに追加のスコープを付与するためにフックを使用します。

module.exports = function(client, scope, audience, context, cb) {
    // Scopes to be added
    var access_token = {};

    // Get the scope that's currently on the Access Token
    // and add it to the object we're working with
    // Do not remove this line!
    access_token.scope = scope;

    // Append the `read:resource` scope
    access_token.scope.push('read:resource');

    // Callback to indicate completion and to return new
    // array of scopes
    cb(null, access_token);
};

詳しくは、「スコープ」をお読みください。

​

応答

このフックを実行すると、応答オブジェクトは次のようになります。

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

​

スクリプト例：アクセストークンにクレームを追加する

この例では、アクセストークンに名前空間のカスタムクレームとその値を追加します。詳細については、「名前空間カスタムクレームを作成する」をお読みください。

以下をクレームとして発行済みトークンに追加できます。

• 応答オブジェクトのscopeプロパティ
• 名前空間プロパティ名のあるすべてのプロパティ

拡張ポイントは、その他すべての応答オブジェクトプロパティを無視します。

構成されたフックシークレットにフック内からアクセスするには、context.webtask.secrets.SECRET_NAMEを使用します。

module.exports = function(client, scope, audience, context, cb) {
    // Claims to be added
    var access_token = {};

    // New claim to add to the token
    access_token['https://example.com/foo'] = 'bar';

    // Callback to indicate completion and to return new claim
    cb(null, access_token);
  };

​

応答

このフックを実行すると、応答オブジェクトは次のようになります。

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

​

スクリプト例：エラーを発生させる、またはアクセストークンを拒否する

この例では、カスタムのエラーオブジェクトを使用して、OAuth2エラー応答を生成します（詳細については、IETF DatatrackerのOAuth2 RFC、セクション5.2をお読みください）。

コールバック内で次のような単純なJavaScriptエラーが返された場合に、

module.exports = function(client, scope, audience, context, cb) {
    // Callback to indicate completion and to return new claim
    cb(new Error("Unknown error occurred.");
  };

/oauth/tokenエンドポイントからclient_credentialsの付与を要求すると、Auth0は次のように応答します。

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

しかし、OAuth2エラー応答をさらに制御したい場合は、3種類のカスタムエラーオブジェクトを使用することもできます。

​

InvalidScopeError

module.exports = function(client, scope, audience, context, cb) {
    const invalidScope = ...; // determine if scope is valid

    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 = ...; // determine if request is valid

    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クラスでは、返されるOAuth2エラーを明示的にすることができます。

​

もっと詳しく