HooksからActionsへの移行

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

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

​

移行を計画する

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

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

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

移行を計画するときのヒント

• フラグを使って、コストがかかる操作や1回限りの操作が重複しないようにします。
• 変更は、影響やトラフィックが最も少ない時間帯や時期に行います。
• 移行のスクリプトを作成し、一括または繰り返してテストと実装が行えるように、Auth0 Deploy CLIの使用を考慮します。

​

制限事項を理解する

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

• Actionsは、アクセストークンやAPI応答などのデータを複数の実行にわたって保持することはできません。
• Actionsには、HooksのようにManagement APIのアクセストークンやグローバルauth0オブジェクトへのアクセスが提供されていません。

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

​

コードを変換する

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

コードを変換するときのヒント

• 一般的に、Actionsのeventオブジェクトについて、Hooks機能に渡されたオブジェクトの読み取り専用プロパティを確認します。
• コードを書くときは、Auth0 DashboardのActions Code Editorを使います。エラーがハイライトされたり、オートコンプリート機能によって提案が自動入力されたりするので、便利です。
• 稼働させる前に、新しいActionsのテストをステージング環境やテスト環境で念入りに行います。

​

フックコードを新しいアクションにコピーする

フックのコードを新しいアクションにコピーし、Auth0 Dashboardの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の関数は名前を付けてエクスポートされます。名前付きエクスポートは、変換するフックの種類によって変化します。マッピングには以下が含まれます。

フックの種類	名前付きエクスポート
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) => {}

// 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レジストリで利用可能なパッケージを要求することができます。

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
};

フックのcontextオブジェクトとは異なり、eventオブジェクトのプロパティで保管・変更されたデータは、他のアクションでは使用できません。フックが、これらのプロパティでデータを設定することでコア機能をトリガーしている場合は、アクション間でデータを保持するために、Machine to Machine（M2M）やPre User Registration（ユーザー登録前）のアクションフローにあるapiインターフェイスを使う必要があります。

​

コールバックを変換する

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

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

​

Client Credentials Exchange（クライアント資格情報の交換）

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（ユーザー登録前）

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でテストできます。