Métadonnées de transaction des Actions

Décrit comment transmettre des métadonnées d’utilisateur ou d’application entre les Actions de connexion et de post-connexion.

Les métadonnées de transaction des Actions servent à stocker, consulter ou partager des métadonnées personnalisées dans une Action de post-login pendant toute la durée d’une transaction.

Auparavant, chaque Action fonctionnait indépendamment, ce qui rendait difficile la transmission d’informations entre elles. Avec les métadonnées de transaction des Actions, il est maintenant possible de :

• Partager des données entre les Actions, comme des réponses d’API ou des calculs intermédiaires.
• Éviter de récupérer de nouveau ou de recalculer les mêmes informations dans différentes Actions.

Avant d’utiliser les métadonnées de transaction en développement, nous vous recommandons de prendre connaissance des limitations. Pour en savoir plus, consultez les limitations des Actions.

​

Fonctionnement

Utilisez l’objet API post-login api.transaction.setMetadata pour définir une paire clé-valeur et stocker des métadonnées de transaction.

Utilisez l’objet Event post-login event.transaction.metadata pour accéder à la paire clé-valeur stockée dans la même Action ou dans des Actions ultérieures sur le déclencheur post-login, au cours d’une même exécution.

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. Si vous la définissez sur null, la propriété est supprimée.

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

​

Latence

L’utilisation des métadonnées de transaction des Actions pourrait entraîner une légère latence supplémentaire. Cette latence serait proportionnelle à la taille de la charge utile des métadonnées et se manifesterait surtout lors des suspensions d’Actions. Par exemple, le déclenchement de MFA, les redirections depuis Actions ou le rendu de Forms pourraient causer des problèmes de latence en raison de la nécessité de recharger les données à partir du stockage.

Cela dit, cette latence potentielle devrait tout de même être moindre que 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éder immédiatement aux métadonnées

Définissez des paires clé-valeur dans les métadonnées de transaction et accédez immédiatement à leurs 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 de type 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 en strings, dans les limites.

Vous ne pouvez pas définir de valeurs de type object ou array, mais vous pouvez les sérialiser en strings.

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 ]" */
};

​

Partager des valeurs entre les Actions

Partagez des paires clé-valeur entre des Actions d’une 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 associée à la clé hello dans les métadonnées de la transaction. Utilisez 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" */
};

​

Mettre à jour les métadonnées

Attribuez une valeur différente à une clé existante 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

Enregistrez la clé sous custom_tx_id et la valeur sous xyz123. Ensuite, attribuez à custom_tx_id la valeur abc456 pour l’enregistrer de nouveau avec sa valeur la plus récente 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 abc456 comme valeur 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

Enregistre 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" */
};

​

Préserver les valeurs lors d’une redirection vers des sites externes

Préservez les métadonnées de transaction lors des redirections. Les valeurs sont accessibles lorsque les utilisateurs continuent 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 du rendu des Forms

Lorsque vous affichez des Forms à l’aide d’Actions, les valeurs des métadonnées de transaction sont conservées et restent 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 formulaire. Ensuite, consigne le custom_tx_id préservé à la reprise de l’exécution des 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" */
};

​

Partager des valeurs avec Forms

Vous pouvez afficher des Forms à l’aide d’Actions et transmettre au formulaire des valeurs des 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 formulaire en transmettant le custom_tx_id des métadonnées de transaction comme paramètre vars. Compare ensuite la valeur de custom_tx_id dans les métadonnées de transaction à celle transmise au formulaire au moment de la reprise de l’exécution des Actions.

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" */
};