HooksからActionsへの移行

既存のHooksをActionsに変換する際には、その種類のフックに対応するトリガーを新しいアクションと関連付ける必要があります。提供するマッピングの識別に沿って以下の手順に従えば、ほぼ同一の機能性に保てるはずです。

デプロイされたActionsはアクティブなHooksの後に実行されるため、Dashboardでフックを一度に1つずつ変換することも、Management APIを使用して一度にすべて変換することもできます。

コードを変換してから、アクションをアクティブにし、フックを非アクティブにする必要があります。アクションの有効化とフックの無効化は、連続してすばやく実行できますが、順序によっては、両方が実行されない、またはどちらも実行されない時間が短期間発生する場合があります。

このため、パイプラインを段階的に移行することをお勧めします。フックコードの一部をアクションコードに変換し、ステージング環境でテストしてから、一度に1つずつライブに移行します。アクティブなHooksはActionsのデプロイ前に作動するため、フック内のいくつかのロジックを構築した状態で維持しつつ、その他のロジックをActionsでテストできます。

ActionsはHooksでできることの大部分を処理できますが、移行を開始する前にいくつかの制限事項に注意する必要があります（注：HooksとActionsはどちらも移行中に実行できます）。

• Actionsは、アクセストークンやAPI応答などのデータを複数の実行にわたって保持することはできません。

• Actionsには、HooksのようにManagement APIのアクセストークンやグローバルauth0オブジェクトへのアクセスが提供されていません。

すべての制限事項については、「Actionsの制限事項」を参照してください。

フックをアクションに変換するには、フック固有のコードをActionsコードに置き換える必要があります。このセクションでは、機能するフックを同等のアクションに変換するためのタスクについて説明します。

1. 運用テナントにログインし、変換元となるフックのコードをコピーします。

2. 非運用テナントに切り替えて、［Auth0 Dashboard］ > ［Actions（アクション）］ > ［Library（ライブラリ）］に移動します。

3. ［Build Custom（カスタムの構築）］を選択した後、

   • 変換するフックの名前と一致するアクションのName（名前）を入力します。

   • ［Trigger（トリガー）］で、適切なトリガーを選択します。

     フックのタイプ	アクションのトリガー
     Client Credentials Exchange（クライアント資格情報交換）	M2M/Client-Credentials（M2M/クライアント資格情報）
     Pre-User-Registration（ユーザー登録前）	Pre User Registration（ユーザー登録前）
     Post-User-Registration（ユーザー登録後）	Post User Registration（ユーザー登録後）
     Post-Change-Password（パスワード変更後）	Post Change Password（パスワード変更後）
     Send Phone Message（電話メッセージの送信）	Send Phone Message（電話メッセージの送信）

   • ［Runtime（ランタイム）］で、［Node 16］を選択します。

   • ［Create（作成）］を選択します。

4. Actionsコードエディターのコードブロックで、変換したいフックコードをエクスポートされた関数の下に貼り付けます。

5. コードを関数に移動するときに、この記事で後述している変更を加えます。Actionsの新しいトリガーに関連付けられたeventオブジェクトについてもお読みください。このガイドの後半で「データへのアクセス方法を変更する」セクションに移動すると、関連するドキュメントへのリンクが表示されます。

Hooksの関数はデフォルトのエクスポートを使ってエクスポートされますが、Actionsの関数は名前を付けてエクスポートされます。名前付きエクスポートは、変換するフックの種類によって変化します。マッピングには以下が含まれます。

変更前

module.exports = async function myHooksFunction(){}

変更後

// Client Credentials Exchange
exports.onExecuteCredentialsExchange = async (event, api) => {}

// Pre-User Registration
exports.onExecutePreUserRegistration = async (event, api) => {}

// Post-User Registration
exports.onExecutePostUserRegistration = async (event) => {}

// Post-Change Password
exports.onExecutePostChangePassword = async (event) => {}

// Send Phone Message
exports.onExecuteSendPhoneMessage = async (event) => {}

HooksとActionsは依存関係を類似した方法で処理します。どちらも、依存関係は、UIまたはManagement APIを使って個別に追加され、コードに含められます。どちらの場合も、npmレジストリで利用可能なパッケージを要求することができます。

1. フックコード内のrequireステートメントを検索してください。

2. バージョン番号を削除しますが、これらの番号はメモしておいてください。

3. 依存関係がコアNodeJSモジュールでない場合は、「初めてアクションを作成する」の「依存関係を追加する」セクションの手順に従って依存関係を追加してください。依存関係がコアNodeJSモジュールである場合は、追加する必要はありません。

4. 見つけたrequireステートメントをfunction宣言の外に移動してください。

HooksとActionsはシークレットを類似した方法で処理します。どちらも、シークレットは、UIまたはManagement APIを使ってフックやアクションごとに追加され、コードに含められます。

シークレットをHooksからActionsに変換するには、以下の手順で行います。

1. 操作中の特定のアクションに必要な値を保存します。

2. アクション内からアクセスする必要がある値ごとにシークレットを追加します。方法については、「初めてアクションを作成する」の「シークレットを追加する」セクションをお読みください。

3. コードを変換します。

変更前

async function (user, context, cb) {
    const { SECRET_NAME } = context.webtask.secrets;

    // ... additional code
}

変更後

async (event, api) => {
    const { SECRET_NAME } = event.secrets;

	// ... additional code
};

フックの場合と同様に、Auth0は保管時のすべてのシークレット値を暗号化します。

フックでは、ユーザーやクライアン、要求についてのデータ、およびその他のコンテキストデータがフック関数に渡される複数の因数に保管されます。Actionsでは、このデータは再形成され、eventオブジェクトに移動します。プロパティの多くはそのまま移行されましたが、わかりやすくするために一部が結合されました。

eventオブジェクトは、変換するフックの種類によって変化します：

• クライアント資格情報の交換 - Actionsイベントオブジェクト

• パスワード変更後- Actionsイベントオブジェクト

• ユーザー登録後 - Actionsイベントオブジェクト

• ユーザー登録前 - Actionsイベントオブジェクト

• 電話メッセージの送信 - Actionsイベントオブジェクト

変更前

async function (user, context, cb) {
	const clientId = context.clientID;
	const tenant = context.connection.tenant

	// ... additional code
}

変更後

async (event, api) => {
	const clientId = event.client.client_id;
	const tenant = event.tenant.id;

	// ... additional code
};

フックの処理が終了したら、callback()関数を呼び出して、実行を完了する必要があります。それとは逆に、Actionsはコールバックのメカニズムを使用しないため、Actionsの関数からcallback()のすべてのインスタンスを削除する必要があります。

callback()関数を使ってクライアント資格情報交換やユーザー登録前のフックで要求を失敗させたりユーザーを更新したりしていた場合でも、Actionsでは新しいapiインターフェースを通じてこれを行うことができます。

Client Credentials Exchange Hook（クライアント資格情報の交換フック）でアクセストークンにクレームを追加する場合には以下を使用していました。

// Client Credentials Exchange Hook
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope;

  access_token['https://example.com/claim'] = 'bar';
  cb(null, access_token);
};

Actionsのクライアント資格情報交換のAPIオブジェクトを使用できます：

// Client Credentials Exchange Action
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};

Pre User Registration Hook（ユーザー登録前のフック）でアクセストークンにクレームを追加する場合には以下を使用していました。

// Pre User Registration Hook
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // This Hook succeeded, proceed with the next Hook.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// This Hook failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}

	// ... additional code
};

Pre User Registration（ユーザー登録前）のAPIオブジェクトを使用できます：

// Pre User Registration Action
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the call with an error response.
		return api.access.deny("Failure message");
	}

	// ... additional code
};

新しいActionsコードを作成してテストしたら、アクションを有効にし、フックを無効にする必要があります。これらの2つのタスクは連続してすばやく実行できますが、順序によっては、両方が実行されない、またはどちらも実行されない時間が短期間発生する場合があります。アクティブなHooksはActionsのデプロイ前に作動するので、ルール内のいくつかのロジックを構築した状態で維持しつつ、その他のロジックをActionsでテストできます。