Actions トランザクションメタデータ

Actions トランザクションメタデータを使用すると、トランザクションの間、カスタムトークン交換 Action と post-login Action 間でカスタムメタデータを保存、参照、共有できます。従来は、各 Action が独立して動作していたため、Action 間で情報を受け渡すのは困難でした。Actions トランザクションメタデータを使うと、次のことが可能になります。

API レスポンスや中間計算結果などのデータを Action 間で共有する。
異なる Action で同じ情報を再取得したり、再計算したりする必要をなくす。
カスタムトークン交換 Action から Post-Login Actions に情報を渡す。

開発でトランザクションメタデータを使用する前に、制限事項を確認することをお勧めします。詳しくは、Actions の制限事項を参照してください。

仕組み

トランザクションメタデータを保存するためのキーと値のペアを設定するには、post-login API object api.transaction.setMetadata を使用します。保存されたキーと値のペアにアクセスするには、post-login Event object event.transaction.metadata を使用します。これにより、同じ Action 内、または 1 回の実行における post-login トリガーの後続の Actions からアクセスできます。 api オブジェクトと event オブジェクトは、カスタムトークン交換 Actions でも使用できます。 API オブジェクトと Event オブジェクトは、次のパラメーターを受け取ります。

Value	Type	Description
`Key`	`String`	設定するメタデータプロパティのキー。
`Value`	`String`, `Number`, `Boolean`	メタデータプロパティの値。 `null` に設定すると、そのプロパティは削除されます。

Actions の記述について詳しくは、Write Your First Action を参照してください。

遅延

Actions Transaction Metadata を使用すると、わずかな遅延が追加で発生する可能性があります。遅延の大きさは metadata のペイロードサイズに比例し、Action の中断が発生する場合に影響します。たとえば、をトリガーする場合、Actions からリダイレクトする場合、または Forms をレンダリングする場合は、ストレージからデータを再読み込みする必要があるため、遅延が問題になる可能性があります。ただし、この遅延の可能性は、一連の Actions で必要なデータを取得するために冗長な外向き HTTP リクエストを行う場合に比べれば、最小限にとどまるはずです。

例

メタデータにすぐアクセスする

トランザクションのメタデータにキーと値のペアを設定し、その値にすぐアクセスできます。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('hello', 'Auth0');

  console.log('Hello ', event.transaction?.metadata?.hello);
  /* "Hello Auth0" を出力 */
};

対応している値を設定する

string、number、boolean 型の値を設定できます。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('string_value', 'Auth0');
  api.transaction.setMetadata('boolean_value', true);
  api.transaction.setMetadata('number_value', 12);

  console.log('string_value', event.transaction?.metadata?.string_value);
  /* "string_value Auth0" を出力 */
  console.log('boolean_value', event.transaction?.metadata?.boolean_value);
  /* "boolean_value true" を出力 */
  console.log('number_value', event.transaction?.metadata?.number_value);
  /* "number_value 12" を出力 */
};

値をシリアライズする

制限事項の範囲内で、値はstringとしてシリアライズします。

object型またはarray型の値は設定できませんが、stringとしてシリアライズすることはできます。

exports.onExecutePostLogin = async (event, api) => {
  const serialized_object_value = JSON.stringify({
    string_value: 'Auth0',
    boolean_value: true,
    number_value: 12
  });

  api.transaction.setMetadata('serialized_object_value', serialized_object_value);

  const serialized_array_value = JSON.stringify([
    'Auth0',
    true,
    12
  ]);
  api.transaction.setMetadata('serialized_array_value', serialized_array_value);

  console.log('serialized_object_value',
    JSON.parse(event.transaction?.metadata?.serialized_object_value)
  );
  /* 出力: "serialized_object_value { string_value: 'Auth0', boolean_value: true, number_value: 12 }" */

  console.log('serialized_array_value',
    JSON.parse(event.transaction?.metadata?.serialized_array_value)
  );
  /* 出力: "serialized_array_value [ 'Auth0', true, 12 ]" */
};

同じ実行シーケンス内の Actions 間で、キーと値のペアを共有します。 Action 1 api オブジェクトの setMetadata メソッドを使って、hello キーに Auth0 という値を設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('hello', 'Auth0');
};

アクション 2 event オブジェクトの transaction.metadata プロパティを使用して設定された値にアクセスし、トランザクションメタデータ内の hello キーに対する Auth0 の値をログに記録します。

exports.onExecutePostLogin = async (event, api) => {
  console.log('Hello', event.transaction?.metadata?.hello);
  /* "Hello Auth0" を出力 */
};

カスタムトークン交換 Actionでキーと値のペアを設定し、同じトランザクション内のPost-Login Actionで読み取ります。たとえば、カスタムトークン交換Actionがsubject_tokenまたはactor_tokenからすでに取得・処理した情報に基づいて、Post-Login Actionでカスタムクレームを設定する場合に便利です。 カスタムトークン交換Action subject_tokenからクレームをデコードし、apiオブジェクトのsetMetadata()メソッドを使用してトランザクションメタデータに設定します。

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token は、Action 内ですでにデコードおよび検証されています
  api.transaction.setMetadata('subject_locale', subjectTokenPayload.locale);
};

Post-Login Action event オブジェクトの transaction.metadata プロパティを使用して、カスタムトークン交換 Action で設定された subject_locale の値を取得し、カスタムクレームを設定します。このクレームは、アクセストークン、ID トークン、またはその両方に追加できます。

exports.onExecutePostLogin = async (event, api) => {
  const locale = event.transaction?.metadata?.subject_locale;
  if (locale) {
    api.idToken.setCustomClaim('https://example.com/locale', locale);
    api.accessToken.setCustomClaim('https://example.com/locale', locale);
  }
};

メタデータを更新する

既存のキーに別の値を設定して、メタデータを更新します。 アクション 1 トランザクションのメタデータのキーと値をそれぞれ custom_tx_id と xyz123 に設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};

アクション 2 キーを custom_tx_id、値を xyz123 として記録します。次に、custom_tx_id を abc456 に設定し、トランザクションメタデータ内の custom_tx_id の最新の値でもう一度記録します。

exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id xyz123" を出力 */

  api.transaction.setMetadata('custom_tx_id', 'abc456');

  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id abc456" を出力 */
};

アクション 3 custom_tx_id の値として abc456 を記録します。

exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id abc456" を出力 */
};

メタデータを削除する

各キーの値を null にすることで、トランザクションメタデータの値を削除できます。 アクション 1 トランザクションメタデータに custom_tx_id を設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};

アクション 2 custom_tx_id を null に設定し、その null 値をログに記録します。

exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id xyz123" を出力 */

  api.transaction.setMetadata('custom_tx_id', null);

  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id undefined" を出力 */
};

アクション 3 custom_tx_id に null 値を記録します。

exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id undefined" を出力 */
};

外部サイトへのリダイレクト時に値を保持する

リダイレクト中も、トランザクションメタデータを保持します。ユーザーが認証フローを再開すると、その値を利用できます。 Action 1 トランザクションメタデータに custom_tx_id を設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};

アクション 2 トランザクションのメタデータに含まれる custom_tx_id を持つトークンを送信して、外部サイトにリダイレクトします。次に、トランザクションのメタデータ内の custom_tx_id の値と、外部サイトに渡され、別のトークンのペイロードで送り返されてきた値を比較します。

exports.onExecutePostLogin = async (event, api) => {
  const token = api.redirect.encodeToken({
    secret: event.secrets.REDIRECT_SECRET,
    expiresInSeconds: 60, 
    payload: {
      custom_tx_id: event.transaction?.metadata?.custom_tx_id,
      continue_uri: `https://${event.secrets.TENANT_DOMAIN}/continue`
    },
  });

  api.redirect.sendUserTo(event.secrets.REDIRECT_URL, {
    query: { session_token: token }
  });
};

exports.onContinuePostLogin = async (event, api) => {
  const payload = api.redirect.validateToken({
    secret: event.secrets.REDIRECT_SECRET
  });

  console.log('Does custon_tx_id match?',
    payload?.custom_tx_id === event.transaction?.metadata?.custom_tx_id
  );
  /* 出力: "Does custon_tx_id match? True" */
};

Forms のレンダリング時に値を保持する

Actions を使用して Forms をレンダリングすると、トランザクションメタデータの値は保持され、ユーザーが認証フローを続行する際にも利用できます。 Actions で Forms を使用する方法について詳しくは、Actions を使用して Forms をレンダリングするを参照してください。 Action 1 トランザクションメタデータに custom_tx_id を設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};

アクション 2 フォームをレンダリングします。次に、Actions の実行を続行する際に、保持された custom_tx_id をログに出力します。

exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(event.secrets.FORM_ID);
};

exports.onContinuePostLogin = async (event, api) => {
  console.log('custon_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* "custom_tx_id xyz123" を出力 */
};

Actions を使って Forms をレンダリングし、トランザクションのメタデータの値を Form に渡せます。 Action 1 トランザクションのメタデータに custom_tx_id を設定します。

exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};

アクション 2 トランザクションメタデータの custom_tx_id を vars パラメーターとして渡し、Form をレンダリングします。次に、Actions の実行を続行する際に、トランザクションメタデータ内の custom_tx_id の値と Form に渡した値を比較します。

exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(event.secrets.FORM_ID, {
    vars: {
      custom_tx_id: event.transaction?.metadata?.custom_tx_id
    }
  });
};

exports.onContinuePostLogin = async (event, api) => {
  console.log('Does custon_tx_id match?',
    event.prompt?.vars?.custom_tx_id === event.transaction?.metadata?.custom_tx_id
  );
  /* 出力: "Does custon_tx_id match? True" */
};

ブランドのカスタマイズ

コードのカスタマイズ

サードパーティーのカスタマイズ

Actions トランザクションメタデータ

仕組み

遅延

例

メタデータにすぐアクセスする

対応している値を設定する

値をシリアライズする

メタデータを更新する

メタデータを削除する

外部サイトへのリダイレクト時に値を保持する

Forms のレンダリング時に値を保持する

​仕組み

​遅延

​例

​メタデータにすぐアクセスする

​対応している値を設定する

​値をシリアライズする

​Actions 間で値を共有する

​カスタムトークン交換からPost-Loginへ値を共有する

​メタデータを更新する

​メタデータを削除する

​外部サイトへのリダイレクト時に値を保持する

​Forms のレンダリング時に値を保持する

​Forms と値を共有する

仕組み

遅延

例

メタデータにすぐアクセスする

対応している値を設定する

値をシリアライズする

Actions 間で値を共有する

カスタムトークン交換からPost-Loginへ値を共有する

メタデータを更新する

メタデータを削除する

外部サイトへのリダイレクト時に値を保持する

Forms のレンダリング時に値を保持する

Forms と値を共有する