ルールからActionsへの移行

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

既存のルールをActionsに移行する際は、新しいActionをログインフローの Post-Login (post-login) トリガーに関連付ける必要があります。以下の手順に従って、Actionsを元のルールと同じ順序にしておけば、動作は変わりません。

​

移行を計画する

Post-Login Actions は既存のルールの後に実行されるため、ルールは Auth0 Dashboard で 1 つずつ変換することも、Management API を使用して一括で変換することもできます。

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

そのため、パイプラインは段階的に移行することをお勧めします。ルールのコードを少しずつ Action のコードに変換し、ステージング環境でテストしてから、1 つずつ本番環境に反映してください。アクティブなルールはデプロイ済みの Actions より前に実行されるため、ルールのパイプラインの最後からさかのぼって作業すれば、Actions で別のロジックを構築してテストしている間も、一部のロジックをルールに残しておけます。

移行計画時のヒント

• Actions とルールは 1:1 で対応させ、機能をひとまとまりごとにオン / オフしてテストできるようにします。
• コストの高い処理や一度きりの処理が重複しないように、ユーザーのメタデータ内のフラグを使用してください。
• ルールのパイプラインの最後からさかのぼって進めてください。アクティブなルールはデプロイ済みの Actions より前に実行されるため、Actions で別のロジックを構築してテストしている間も、一部のロジックをルールに残しておけます。
• 変更は、影響やトラフィックが最も少ない時間帯に実施するようにしてください。
• 切り替えによって無効なログインや保護の抜け漏れが発生する可能性がある場合は、一時的に ログインページをカスタマイズ してログインを停止することを検討してください。
• Auth0 Deploy CLI を使用して移行をスクリプト化し、テストし、一括または段階的にすばやく実施することを検討してください。

​

制限事項を理解する

Actions はルールでできることの大半に対応していますが、移行を始める前にいくつかの制限事項を理解しておく必要があります。 (移行中はルールと Actions の両方を実行できることも覚えておいてください。)

• Actions では、ルールのように Management API 用のアクセストークン やグローバルな auth0 オブジェクトへのアクセスは提供されません。Management API の呼び出しを引き続き行う方法については、Convert Code セクションを参照してください。

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

​

コードを変換する

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

コード変換時のヒント

• 一般的には、ルールの user オブジェクトと context オブジェクトにある読み取り専用プロパティは、Actions の event オブジェクト内で確認します。Actions がシステムに及ぼす副作用 (ログインの失敗やユーザーのメタデータの更新など) は、api オブジェクトの関数で扱います。
• コードの作成には、Auth0 Dashboard の Actions Code Editor を使用してください。エラーのハイライト表示や自動補完候補の提示により、効率よく作業できます。
• 本番環境に移行する前に、新しい Actions を十分にテストし、ステージング環境またはテスト環境 でしっかり検証してください。

​

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

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

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

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

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

   • 変換する ルール と同じ名前を Name に入力します。
   • トリガー を探し、Login / Post Login を選択します。
   • Runtime を探し、Node 16. を選択します。
   • Create を選択します。

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

5. コードをその関数内に移しながら、この記事の以降のセクションで説明する変更を加えます。

​

関数宣言を変更する

ルールでは user、context、callback をパラメーターに取る通常の関数宣言を使用しますが、Actions では特定の名前でエクスポートされた関数を使用します。次のように変更してください。現時点では、表示されるエラーは無視して構いません。

変更前

async function myRulesFunction(user, context, callback) {
    // ... 追加のコード
}

変更後

exports.onExecutePostLogin = async (event, api) => {
	// ... 追加コード
};

​

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

ルールでは、ログインするユーザーに関するデータは user オブジェクト に格納されます。Actions では、このデータは event オブジェクト の user プロパティに格納されています。既存のプロパティの大半には、この新しい場所からアクセスできます。

event オブジェクトのプロパティに保存または変更されたデータには、他の Actions からアクセスできません。

変更前

function myRulesFunction(user, context, callback) {
	const userEmail = user.email;
	const userId = user.user_id;

	// このプロパティはルールでは未定義になる可能性があります。
	const userAppMetadata = user.app_metadata || {};

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

変換後

exports.onExecutePostLogin = async (event, api) => {
	const userEmail = event.user.email;
	const userId = event.user.user_id;

	// このプロパティはActionsでundefinedになることはありません。
	const userAppMetadata = event.user.app_metadata;

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

​

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

ルールでは、現在のログインセッションに関するデータは context オブジェクト に格納されます。Actions では、このデータは再構成され、event オブジェクト に移されました。多くのプロパティはそのまま移行されていますが、わかりやすくするために一部は統合されています。

event オブジェクトのプロパティに保存または変更されたデータは、他の Actions からはアクセスできません。context.idToken や context.multifactor のように、これらのプロパティにデータを設定することでルールがコア機能をトリガーしている場合は、ユースケースに対応する以下のいずれかのセクションをお読みください。

変更前

function myRulesFunction(user, context, callback) {
	const clientId = context.clientID;
	const clientMetadata = context.clientMetadata || {};

	const connectionId = context.connectionID;
	const connectionMetadata = context.connectionMetadata || {};

	const protocol = context.protocol;

	const tenant = context.tenant;

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

変換後

exports.onExecutePostLogin = async (event, api) => {
	const clientId = event.client.client_id;
	const clientMetadata = event.client.metadata;

	const connectionId = event.connection.id;
	const connectionMetadata = event.connection.metadata;

	const protocol = event.transaction.protocol;

	const tenant = event.tenant.id;

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

​

依存関係を変換する

ルールでは、依存関係を require 文にバージョン番号を含める形で記述する必要があります。Actions では、より標準的な CommonJS 構文を使用し、バージョンはコードエディターの外で指定します。

ルールでは、使用できるのは特定のパッケージの特定バージョンに限られており、新しいパッケージやバージョンを追加するには Auth0 への申請が必要です。Actions では、npm Registry で利用可能な任意のパッケージを require できます。

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

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

変換前

function myRulesFunction(user, context, callback) {
	const dependency = require("dependency@1.2.3");

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

変換後

const dependency = require("dependency"); // v1.2.3
exports.onExecutePostLogin = async (event, api) => {
	// ... 追加のコード
};

​

コールバックの変換

ルール での処理が完了したら、callback() 関数を呼び出し、ログインに失敗した場合はエラーを渡す必要があります。一方、Actions では成功時は return でき、ログインに失敗した場合はメッセージを指定して api メソッドを呼び出せます。ルール 内の callback() はすべて削除するか、失敗時には api.access.deny() に置き換える必要があります。ルールと Actions のどちらでも、特定の条件で処理を中断する必要がある場合は、return 文を使用します。

変更前

function myRulesFunction(user, context, callback) {
	const userAppMetadata = user.app_metadata || {};
	if (userAppMetadata.condition === "success") {
		// このRuleは成功しました。次のRuleに進みます。
		return callback(null, user, context);
	}

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

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

変更後

exports.onExecutePostLogin = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// このActionは成功しました。次のActionに進みます。
		return;
	}

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

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

​

secrets の扱いを変更する

ルールでは、設定値をグローバルに設定するため、すべてのルールからすべてのシークレット値にアクセスできます。 (詳しくは、ルール の設定を保存する をご覧ください。) 一方、Actions では設定値を Action ごとに設定します。Action のコンテキスト外から、その Action のシークレット値にアクセスすることはできません。

ルールの secrets を Actions に移行するには、次の手順を行います。

1. 作業中の Action に必要な値を保存します。
2. Action 内からアクセスする必要がある値ごとに Secret を追加します。方法については、初めてのActionを書く の Secret を追加する セクションを参照してください。
3. コードを変換します。

変換前

function myRulesFunction (user, context, callback) {
  const { CLIENT_ID, CLIENT_SECRET } = configuration;

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

変換後

exports.onExecutePostLogin = async (event, api) => {
  const { CLIENT_ID, CLIENT_SECRET } = event.secrets;

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

ルールと同様に、Auth0 では保存時にすべてのシークレット値が暗号化されます。

​

トークン内のカスタムクレームを変換する

ルールと Actions はどちらも、ID トークンとアクセストークンにカスタムクレームを追加できます。ルールではこれは context オブジェクトのプロパティですが、Actions では api オブジェクト のメソッドを使用します。

変換前

function myRulesFunction(user, context, callback) {
	const userAppMetadata = user.app_metadata || {};
	const namespace = "https://namespace/";

	context.idToken[`${namespace}/emp_id`] = userAppMetadata.emp_id;
	context.accessToken[`${namespace}/emp_id`] = userAppMetadata.emp_id;

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

変換後

exports.onExecutePostLogin = async (event, api) => {
	const namespace = "https://namespace/";

	api.idToken.setCustomClaim(
		`${namespace}/emp_id`, 
		event.user.app_metadata.emp_id
	); 		   

	api.accessToken.setCustomClaim(
		`${namespace}/emp_id`, 
		event.user.app_metadata.emp_id
	);

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

​

多要素認証のトリガー設定を移行する

ルールでは、多要素認証 は context オブジェクト の multifactor プロパティを変更することでトリガーできます。Actions では、api オブジェクトのメソッド を使用してこれを行います。

変換前

function myRulesFunction(user, context, callback) {
	if (user.app_metadata.needs_mfa === true) {
		context.multifactor = { 
			provider: "any", 
			allowRememberBrowser: false,
		};
	}

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

変換後

exports.onExecutePostLogin = async (event, api) => {
	if (event.user.app_metadata.needs_mfa === true) {
		api.multifactor.enable("any", { allowRememberBrowser: false });
	}

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

​

ユーザーメタデータの更新を変換する

ルールで user_metadata と app_metadata プロパティを更新するには Management API を呼び出す必要があり、レート制限 エラーが発生する可能性があります。一方、Actions では複数のユーザーメタデータの変更を指定しても、Management API の呼び出しは 1 回で済みます。

変換前

function myRulesFunction(user, context, callback) {
	user.app_metadata = user.app_metadata || {}; 
	user.app_metadata.roles = user.app_metadata.roles || [];
	user.app_metadata.roles.push("administrator"); 

	auth0.users
		.updateAppMetadata(user.user_id, user.app_metadata) 
		.then(() => callback(null, user, context))
		.catch((err) => callback(err));

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

後続のルールでもユーザーのメタデータを更新する必要がある場合は、Management API をその都度別途呼び出す必要があり、レート制限 に達しやすくなります。

変更後

exports.onExecutePostLogin = async (event, api) => {
	const userRolesUpdated = event.user.app_metadata.roles || [];
	userRolesUpdated.push("administrator"); 

	// ここでは2つの異なるメソッドを使用していることに注意してください。 
	api.user.setAppMetadata("roles", userRolesUpdated);
	api.user.setUserMetadata("hasRoles", true);

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

後続のActionsでユーザーのメタデータを更新する必要がある場合は、api.user.setUserMetadata または api.user.setAppMetadata を呼び出す必要があります。Actions では、1 つ以上のActionsにまたがってこれらの関数が複数回呼び出された場合でも、フローの完了後に実行される Management API 呼び出しは 1 回だけです。

​

他の Management API 呼び出しを変換する

一般に、ルールや Actions のような高トラフィックで重要な処理経路から Management API を呼び出すことは推奨されません。拡張ポイントからの呼び出しを含め、Auth0 のすべての API へのリクエストにはレート制限があるため、すべてのログイン時に API を呼び出すと、トラフィックが多い時間帯にはログイン失敗につながりかねません。

ただし、その呼び出しが必要であり、レート制限に抵触しないよう構成されていれば、Actions 内から Management API を呼び出すことは可能です。この記事前半の “制限事項を理解する” セクションで述べたとおり、Actions には Management API 用のアクセストークンが提供されないため、Action を有効化する前にアクセストークンを取得する必要があります。

1. Machine-to-Machine アプリケーションを登録し、Management API へのアクセスを許可します。

2. Client ID と Client Secret を Action に保存します。

3. Management API 用のアクセストークンを取得します。

4. Management API を呼び出します。

   Actions は実行をまたいでデータを保持できないため、アクセストークンを一定時間キャッシュすることはできません。さらに、Management API の呼び出しごとに Authentication API の呼び出しも必要になるため、Management API の呼び出しは非常にコストの高い処理です。

変換前

function myRulesFunction(user, context, callback) {
	const ManagementClient = require("auth0@2.9.1").ManagementClient; 
	const managementClientInstance = new ManagementClient({
		// これらは組み込みのルールのグローバル変数から取得されます
		token: auth0.accessToken, 
		domain: auth0.domain,
	}); 

	managementClientInstance.users.assignRoles(
		{ id: user.user_id }, 
		{ roles: ["ROLE_ID_TO_ADD"] }, 
		(error, user) => {
			if (error) {
				return callback(error);
			}

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

変換後

const auth0Sdk = require("auth0");
exports.onExecutePostLogin = async (event, api) => {
	const ManagementClient = auth0Sdk.ManagementClient;

	// これにより Authentication API の呼び出しが行われます
	const managementClientInstance = new ManagementClient({
		// これらは machine-to-machine アプリケーションから取得します
		domain: event.secrets.M2M_DOMAIN,
		clientId: event.secrets.M2M_CLIENT_ID,
		clientSecret: event.secrets.M2M_CLIENT_SECRET,
		scope: "update:users"
	});

	managementClientInstance.users.assignRoles(
		{ id: event.user.user_id }, 
		{ roles: ["ROLE_ID_TO_ADD"]}, 
		(error, user) => {
			if (error) {
				return api.access.deny(error.message);
			}

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

​

リダイレクトの変換

ルールでは、ログイン中のユーザーを外部ページにリダイレクトし、その後でレスポンスを待つことができます。この場合、リダイレクト前にあるすべてのルールが 2 回実行されます。1 回はリダイレクト前、もう 1 回はレスポンス受信時です。通常、リダイレクト用とレスポンス処理用のロジックは同じルールに含まれます。

Actions では、リダイレクトが発生すると Action パイプラインは一時停止し、ユーザーが戻ると処理が再開されます。また、リダイレクトをトリガーするエクスポート関数は、リダイレクトのコールバックとは別になっています。

Actions でリダイレクトを正しく実装する方法をすべてこのガイドで扱うことはできません。詳しくは、Actions でのリダイレクトを参照してください。

変換前

function myRulesFunction(user, context, callback) {
    if (context.protocol === "redirect-callback") {
        // ユーザーは /continue エンドポイントにリダイレクトされた
        user.app_metadata.wasRedirected = true;
        return callback(null, user, context);
    } else if (
        context.protocol === "oauth2-password" ||
        context.protocol === "oauth2-refresh-token" ||
        context.protocol === "oauth2-resource-owner"
    ) {
        // ユーザーはリダイレクトできない
        return callback(null, user, context);
    }
    // ユーザーは直接ログインしている
    if (!user.app_metadata.wasRedirected) {
        context.redirect = {
            url: "https://example.com",
        };
        callback(null, user, context);
    }
}

変更後

exports.onExecutePostLogin = async (event, api) => {
    api.accessToken.setClaim("https://dev.TLD/wasRedirected", true)

​

現在の SSO クライアント参照を変換する

ルールの context.sso オブジェクトには、現在のセッションと、そのセッションを使用しているクライアントの詳細情報が含まれます。詳しくは、ルールにおけるコンテキストオブジェクトのプロパティ の context.sso の項目を参照してください。同様の情報は、Actions の event.session オブジェクトでも利用できます。

変更前

function (user, context, callback) {

  const clients = context.sso?.current_clients ?? []; 

  if (clients.length > 0) { 
	context.idToken.clients = clients.join(" "); 
  }

  return callback(null, user, context);
}

移行後

exports.onExecutePostLogin = async (event, api) => {
  const clients = event?.session?.clients ?? []; 

  if (clients.length > 0) { 
    api.idToken.setCustomClaim('clients', clients.map(c=> c?.client_id).join(" ")); 
  }
};

​

移行を完了する

新しいActionsのコードの作成とテストが完了したら、Actionを有効化し、ルールを無効化する必要があります。この2つの作業は短時間で続けて行えますが、順番によっては、両方が動作する時間帯、またはどちらも動作しない時間帯が短時間発生する可能性があります。有効なルールはデプロイ済みのActionsより先に実行されるため、ルールパイプラインの末尾から逆向きに進めることで、Actionsでほかのロジックを構築・テストしている間も、一部のロジックをルールに残しておけます。