Actions Transaction Metadata

Actions Transaction Metadata permet de stocker, de consulter et/ou de partager des métadonnées personnalisées pendant toute la durée d’une transaction, entre les Actions Custom Token Exchange et post-login. Auparavant, chaque Action fonctionnait de façon indépendante, ce qui compliquait la transmission d’informations entre elles. Avec Actions Transaction Metadata, il est maintenant possible de :

Partager des données entre les Actions, comme des réponses d’API ou des calculs intermédiaires.
Éliminer la nécessité de récupérer à nouveau ou de recalculer la même information dans différentes Actions.
Transmettre l’information d’une Action Custom Token Exchange vers les Post-Login Actions.

Avant d’utiliser les métadonnées de transaction en développement, nous vous recommandons de consulter les limites. Pour en savoir plus, consultez Actions Limitations.

Fonctionnement

Utilisez l’objet API post-login api.transaction.setMetadata pour définir une paire clé-valeur afin de stocker des métadonnées de transaction. Utilisez l’objet Event post-login event.transaction.metadata pour accéder à une paire clé-valeur stockée dans la même Action ou dans des Actions ultérieures du trigger post-login, au cours d’une même exécution. Les objets api et event sont également disponibles dans les Actions Custom Token Exchange. Les objets API et Event acceptent les paramètres suivants :

Valeur	Type	Description
`Key`	`String`	La clé de la propriété de métadonnées à définir.
`Value`	`String`, `Number`, `Boolean`	La valeur de la propriété de métadonnées. La définir à `null` supprime la propriété.

Pour en savoir plus sur la création d’Actions, consultez Write Your First Action.

Latence

L’utilisation de Actions Transaction Metadata pourrait entraîner une légère latence supplémentaire. Cette latence serait proportionnelle à la taille de la charge utile de métadonnées et se manifesterait lors des suspensions d’Actions. Par exemple, le déclenchement de , les redirections à partir de Actions ou le rendu de Forms pourraient causer des problèmes de latence, puisqu’il faut recharger les données à partir du stockage. Cela dit, cette latence potentielle devrait rester inférieure à celle causée par des requêtes HTTP sortantes redondantes pour récupérer les données dont la séquence d’Actions a besoin.

Exemples

Accédez immédiatement aux métadonnées de transaction

Définissez des paires clé-valeur dans les métadonnées de transaction et accédez immédiatement aux valeurs.

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

  console.log('Hello ', event.transaction?.metadata?.hello);
  /* Affiche « Hello Auth0 » */
};

Définir les valeurs prises en charge

Définissez des valeurs des types suivants : string, number et 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);
  /* Affiche "string_value Auth0" */
  console.log('boolean_value', event.transaction?.metadata?.boolean_value);
  /* Affiche "boolean_value true" */
  console.log('number_value', event.transaction?.metadata?.number_value);
  /* Affiche "number_value 12" */
};

Sérialiser des valeurs

Sérialisez les valeurs sous forme de chaînes de caractères dans les limites.

Vous ne pouvez pas définir des valeurs de type objet ou tableau, mais vous pouvez les sérialiser en chaînes de caractères.

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)
  );
  /* Affiche "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)
  );
  /* Affiche "serialized_array_value [ 'Auth0', true, 12 ]" */
};

Partagez des paires clé-valeur entre les Actions dans la même séquence d’exécution. Action 1 Définissez la clé hello sur la valeur Auth0 à l’aide de la méthode setMetadata de l’objet api.

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

Action 2 Consignez la valeur Auth0 de la clé hello dans les métadonnées de transaction à l’aide de la propriété transaction.metadata de l’objet event pour accéder aux valeurs définies.

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

Définissez une paire clé-valeur dans une Action Custom Token Exchange, puis lisez-la dans une Action Post-Login au cours de la même transaction. Cela est utile, par exemple, pour définir une revendication personnalisée dans l’Action Post-Login à partir de renseignements que votre Action Custom Token Exchange a déjà obtenus ou traités depuis le subject_token ou l’actor_token. Action Custom Token Exchange Décodez une revendication du subject_token et définissez-la comme métadonnées de transaction à l’aide de la méthode setMetadata() de l’objet api.

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token a déjà été décodé et validé plus tôt dans l’Action
  api.transaction.setMetadata('subject_locale', subjectTokenPayload.locale);
};

Action post-login Lisez la valeur subject_locale définie par l’Action Custom Token Exchange à l’aide de la propriété transaction.metadata de l’objet event, puis utilisez-la pour définir une revendication personnalisée. La revendication peut être ajoutée au jeton d’accès, au jeton ID ou aux deux.

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

Mettre à jour les métadonnées

Définissez une clé existante avec une valeur différente pour mettre à jour les métadonnées. Action 1 Définissez la paire clé-valeur des métadonnées de transaction sur custom_tx_id et xyz123.

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

Action 2 Consignez la clé custom_tx_id et la valeur xyz123. Ensuite, définissez custom_tx_id sur abc456 pour consigner de nouveau la valeur la plus récente de custom_tx_id dans les métadonnées de transaction.

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

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

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

Action 3 Consignez la valeur abc456 de custom_tx_id.

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

Supprimer les métadonnées

Supprimez les valeurs des métadonnées de transaction en attribuant la valeur null à chaque clé concernée. Action 1 Définissez custom_tx_id dans les métadonnées de transaction.

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

Action 2 Définissez custom_tx_id sur null et consignez la valeur null de custom_tx_id.

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

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

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

Action 3 Consigne la valeur null pour custom_tx_id.

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

Conserver les valeurs lors d’une redirection vers des sites externes

Conservez les métadonnées de transaction pendant les redirections. Les valeurs sont accessibles lorsque les utilisateurs reprennent le flux d’authentification. Action 1 Définit un custom_tx_id dans les métadonnées de transaction.

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

Action 2 Redirige vers un site externe en envoyant un jeton contenant le custom_tx_id issu des métadonnées de la transaction. Ensuite, compare la valeur de custom_tx_id dans les métadonnées de la transaction à celle transmise au site externe, puis renvoyée dans la charge utile d’un autre jeton.

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
  );
  /* Affiche "Does custon_tx_id match? True" */
};

Préserver les valeurs lors de l’affichage des Forms

Les valeurs des Forms affichés à l’aide d’Actions et les valeurs des métadonnées de transaction seront conservées et resteront accessibles lorsque les utilisateurs poursuivent le flux d’authentification. Pour en savoir plus sur l’utilisation de Forms avec Actions, consultez Afficher des Forms à l’aide d’Actions. Action 1 Définit un custom_tx_id dans les métadonnées de transaction.

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

Action 2 Affiche un Form. Consigne ensuite le custom_tx_id conservé à la reprise de l’exécution d’Actions.

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);
  /* Affiche "custom_tx_id xyz123" */
};

Vous pouvez utiliser Actions pour afficher des Forms et transmettre au Form des valeurs de métadonnées de transaction. Action 1 Définit un custom_tx_id dans les métadonnées de transaction.

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

Action 2 Affiche un Form en passant le custom_tx_id des métadonnées de la transaction comme paramètre vars. Il compare ensuite la valeur de custom_tx_id dans les métadonnées de la transaction à celle transmise au Form lorsque l’exécution des Actions se poursuit.

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
  );
  /* Affiche "Does custon_tx_id match? True" */
};

Personnalisation de la marque

Personnalisation du code

Personnalisation tierce

Actions Transaction Metadata

Fonctionnement

Latence

Exemples

Accédez immédiatement aux métadonnées de transaction

Définir les valeurs prises en charge

Sérialiser des valeurs

Mettre à jour les métadonnées

Supprimer les métadonnées

Conserver les valeurs lors d’une redirection vers des sites externes

Préserver les valeurs lors de l’affichage des Forms

​Fonctionnement

​Latence

​Exemples

​Accédez immédiatement aux métadonnées de transaction

​Définir les valeurs prises en charge

​Sérialiser des valeurs

​Partager des valeurs entre les Actions

​Partager des valeurs entre Custom Token Exchange et Post-Login

​Mettre à jour les métadonnées

​Supprimer les métadonnées

​Conserver les valeurs lors d’une redirection vers des sites externes

​Préserver les valeurs lors de l’affichage des Forms

​Partager des valeurs avec Forms

Fonctionnement

Latence

Exemples

Accédez immédiatement aux métadonnées de transaction

Définir les valeurs prises en charge

Sérialiser des valeurs

Partager des valeurs entre les Actions

Partager des valeurs entre Custom Token Exchange et Post-Login

Mettre à jour les métadonnées

Supprimer les métadonnées

Conserver les valeurs lors d’une redirection vers des sites externes

Préserver les valeurs lors de l’affichage des Forms

Partager des valeurs avec Forms