Hooks から Actions への移行

既存の Auth0 Hooks のコードを Auth0 Actions のコードへ移行する方法を学びます。

既存の Hooks を Actions に変換する際は、新しい Action を、その Hook の種類に対応するトリガーに関連付ける必要があります。以下の手順に従い、その中で示す対応関係を使用すれば、同じ機能を実現できます。

​

移行を計画する

デプロイ済みのActionsは有効なHooksの後に実行されるため、Hooksを1つずつAuth0 Dashboardで変換することも、Management API を使用して一括で変換することもできます。

コードを変換した後、Actionを有効化し、Hookを無効化する必要があります。Actionの有効化とHookの無効化はすぐ続けて実行できますが、順序によっては、短時間だけ両方が実行されたり、どちらも実行されなかったりする可能性があります。

そのため、パイプラインは段階的に移行することをお勧めします。Hooksのコードを部分ごとにActionのコードへ変換し、ステージング環境でテストしてから、1つずつ本番環境に反映してください。有効なHooksはデプロイ済みのActionsより先に実行されるため、Actionsで別のロジックを構築・テストしている間も、一部のロジックはHooksに残しておけます。

移行を計画する際のヒント

• コストの高い処理や一度しか実行してはならない処理が重複しないよう、フラグを使用してください。
• 変更は、影響とトラフィックが最も少ない時間帯に実施してください。
• Auth0 Deploy CLI を使用して、移行全体を一括または段階的にスクリプト化し、テストして、すばやく実装することを検討してください。

​

制限事項を理解する

Actions は Hooks でできることの大半に対応していますが、移行を始める前に、いくつかの制限事項を把握しておく必要があります。 (注意: 移行中は Hooks と Actions の両方を同時に実行できます。)

• Actions では、アクセストークン や API レスポンスのようなデータを、実行間で保持することはできません。
• Actions では、Hooks のように Management API 用のアクセストークン や グローバル auth0 オブジェクトへのアクセス は利用できません。

制限事項の一覧については、Actions Limitations を参照してください。

​

コードを変換する

Hook を Action に変換するには、Hook 固有のコードを Actions のコードに置き換える必要があります。このセクションでは、動作中の Hook を対応する Action に変換するために必要な作業について説明します。

コード変換時のヒント

• 基本的には、Hooks 関数に渡されるオブジェクトの読み取り専用プロパティに相当するものを、Actions の event オブジェクトで探してください。
• コードの作成には Auth0 Dashboard の Actions Code Editor を使用してください。エラーのハイライト表示や自動補完候補の提示に役立ちます。
• 本番環境に移行する前に、新しい Actions を十分にテストし、ステージング環境またはテスト環境 で入念に確認してください。

​

Hook のコードを新しい Action にコピーする

Hook のコードを新しい Action にコピーし、Auth0 Dashboard の Actions Code Editor を使用することをお勧めします。これにより、コードに残っている問題を特定しやすくなります。

1. 本番テナントにログインし、変換したい Hook からコードをコピーします。

2. 非本番テナントに切り替え、Auth0 Dashboard > Actions > Library に移動します。

3. Build Custom を選択し、次の操作を行います。

   • 変換する Hook の名前と一致する Action の Name を入力します。

   • Trigger で、適切なトリガーを選択します**:**

     Hook の種類	Actions のトリガー
     Client Credentials Exchange	M2M/Client-Credentials
     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 18 を選択します。

   • Create を選択します。

4. Actions Code Editor のコードブロックで、変換したい Hook のコードを export された関数の下に貼り付けます。

5. コードを関数内に移しながら、この記事の残りの部分で説明されている変更を加えます。 また、新しい Actions のトリガーに関連付けられた event オブジェクトについても確認してください。このガイドの後半にある データへのアクセス方法を変更する セクションに進むと、関連ドキュメントへのリンクが表示されます。

​

関数宣言を変更する

フックの関数はデフォルトエクスポートでエクスポートされますが、Actions の関数は名前付きエクスポートを使用します。変換する Hook の種類に応じて、使用する名前付きエクスポートも変わります。対応は次のとおりです。

フックの種類	名前付きエクスポート
Client Credentials Exchange	onExecuteCredentialsExchange
Pre-User Registration	onExecutePreUserRegistration
Post-User Registration	onExecutePostUserRegistration
Post-Change Password	onExecutePostChangePassword
Send Phone Message	onExecuteSendPhoneMessage

変更前

module.exports = async function myHooksFunction(){}

変換後

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

// ユーザー登録前
exports.onExecutePreUserRegistration = async (event, api) => {}

// ユーザー登録後
exports.onExecutePostUserRegistration = async (event) => {}

// パスワード変更後
exports.onExecutePostChangePassword = async (event) => {}

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

​

依存関係を移行する

フックとActionsでは、依存関係はほぼ同じ方法で扱います。どちらも、依存関係をUIまたはManagement APIから個別に追加し、コード内で使用します。また、どちらでもnpm Registryで利用可能な任意のパッケージをrequireできます。

npmモジュールが最新バージョンでない場合は、今がアップデートの絶好の機会です。

1. Hookコード内のrequire文を検索します。
2. バージョン番号を削除し、その番号はメモしておきます。
3. 依存関係がNodeJSのコアモジュールでない場合は、Write Your First Action の「Add a Dependency」セクションの手順に従って追加します。コアモジュールであれば、追加する必要はありません。
4. 見つかったrequire文をfunction宣言の外に移動します。

​

シークレットを変換する

Hooks と Actions では、シークレットはほぼ同じように扱われます。どちらも、Secrets は UI または Management API を使って Hook/Action ごとに追加し、コード内で利用します。

Hooks のシークレットを Actions に変換するには、次の手順を実行します。

1. 作業中の Action に必要な値を控えておきます。
2. Action 内からアクセスする値ごとに Secret を追加します。追加方法については、Write Your First Action の Add a Secret セクションを参照してください。
3. コードを変換します。

Before

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

    // ... 追加のコード
}

変更後

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

	// ... 追加のコード
};

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

​

データへのアクセス方法を変更する

Hooks では、ユーザー、クライアント、リクエスト、そのほかのコンテキストデータに関する情報は、Hook 関数に渡される複数の引数に格納されています。Actions では、これらのデータは再構成され、event オブジェクトに移されています。多くのプロパティはそのまま移行されていますが、わかりやすくするために統合されたものもあります。

変換する Hook の種類によって、event オブジェクトの内容は異なります。

• Client Credentials Exchange - Actions イベントオブジェクト
• Post-Change Password - Actions イベントオブジェクト
• Post-User Registration - Actions イベントオブジェクト
• Pre-User Registration - Actions イベントオブジェクト
• Send Phone Message - Actions イベントオブジェクト

変換前

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

	// ... 追加のコード
}

変換後

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

	// ... 追加のコード
};

Hooks の context オブジェクトとは異なり、event オブジェクトのプロパティに保存または変更されたデータは、後続の Actions には引き継がれません。Hook でこれらのプロパティにデータを設定してコア機能をトリガーしている場合は、Actions 間でデータを保持するために、Machine to Machine および Pre User Registration の Actions Flows で利用できる api インターフェースを使用する必要があります。

​

コールバックを変換する

Hook での処理が完了したら、実行を完了するために callback() 関数を呼び出す必要があります。一方、Actions ではコールバックの仕組みを使用しないため、Actions 関数から callback() の呼び出しをすべて削除する必要があります。

以前、Client Credentials Exchange または Pre User Registration Hook で、リクエストを失敗させたりユーザーを更新したりするために callback() 関数を使用していた場合でも、Actions では新しい api インターフェースを通じて引き続きこれを行えます。

​

Client Credentials Exchange

Client Credentials Exchange Hook で access token に追加のクレームを設定していた場合:

// 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のClient Credentials Exchange API オブジェクトを使用できるようになりました：

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

​

Pre User Registration

Pre User Registration Hook で access token に追加のクレームを設定していた場合:

// 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" } };
      // このHookは成功しました。次のHookに進みます。
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// このHookは失敗しました。エラーレスポンスでログインを停止します。
		return callback(new Error("Failure message"));
	}

	// ... 追加コード
};

これで、Pre User Registration API Objectを使用できるようになりました:

// Pre User Registration Action（事前ユーザー登録）
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// このActionは成功しました。次のActionに進みます。
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// このActionは失敗しました。エラーレスポンスで処理を停止します。
		return api.access.deny("Failure message");
	}

	// ... 追加のコード
};

​

移行を完了する

新しいActionsのコードを作成してテストしたら、Actionを有効化し、Hookを無効化する必要があります。これら2つの作業は立て続けにすばやく行えますが、順序によっては、短時間だけ両方が実行されたり、どちらも実行されなかったりする可能性があります。有効なHooksはデプロイ済みのActionsより先に実行されるため、Actionsで別のロジックを構築してテストしている間も、一部のロジックをルールに残しておくことができます。