Déclencheurs Actions : custom-token-exchange - objet API

Découvrez l’objet API du déclencheur Action custom-token-exchange.

L’objet API du déclencheur Action custom-token-exchange comprend :

​

api.access

Modifiez l’accès à la requête d’échange de jeton, par exemple en la rejetant.

​

api.access.deny(code, reason)

Indique que l’échange de jetons en cours est refusé.

Si la requête est refusée en raison d’un jeton du sujet non valide, nous recommandons d’utiliser plutôt api.access.rejectInvalidSubjectToken, afin de distinguer les tentatives par force brute sur le jeton du sujet des autres motifs de refus de la requête.

code · string

Le code d’erreur justifiant le rejet de l’échange de jetons. Il peut s’agir de invalid_request, server_error ou de tout code personnalisé.

reason · string

Une explication lisible par un humain du rejet de la requête d’échange de jetons.

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre stratégie d'autorisation sur l'utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // si l'utilisateur est autorisé, continuer comme indiqué ici

};

​

api.access.rejectInvalidSubjectToken(reason)

Marque le jeton du sujet fourni dans la requête comme invalide. La requête sera alors rejetée avec le code d’erreur “invalid_request”.

Cette opération signale aux fonctionnalités Attack Protection qu’un jeton du sujet invalide a été fourni, afin que des protections contre les attaques par force brute visant le jeton du sujet puissent être appliquées.

reason · string

Une explication en langage clair du rejet de la requête d’échange de jeton.

exports.onExecuteCustomTokenExchange = async (event, api) => {

  try {
    // Valider le subject_token
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // définir l'utilisateur pour la transaction
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // Si le problème vient précisément du fait que le subject_token est invalide
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // s'il y a toute autre erreur inattendue, générer une erreur serveur
      throw error;
    }
  }

};

​

api.authentication

Indique le résultat de l’authentification du jeton du sujet afin de préciser l’utilisateur pour lequel des jetons seront émis.

​

api.authentication.setUserById(user_id)

Indiquez l’utilisateur correspondant au subject_token en fournissant le userId. La requête d’échange de jetons émettra des jetons pour cet utilisateur. Il doit s’agir d’un utilisateur existant. Remarque : Une seule des méthodes suivantes, api.authentication.setUserByConnection ou api.authentication.setUserById, doit être appelée par l’Action Custom Token Exchange.

user_id · string

ID de l’utilisateur ; doit correspondre à un utilisateur existant.

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre stratégie d'autorisation à l'utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l'utilisateur pour la transaction
  api.authentication.setUserById(subject_token.sub);

  return;
};

​

api.authentication.setUserByConnection(connection_name, user_attributes, options)

Indiquez l’utilisateur correspondant au subject_token en fournissant une connexion et des attributs utilisateur. La requête d’échange de jeton émettra des jetons pour cet utilisateur.

Il peut s’agir d’un utilisateur existant ou d’un nouvel utilisateur. Si l’utilisateur n’existe pas, il sera créé. La propriété user_id du user_profile sera utilisée pour déterminer si l’utilisateur existe déjà.

Remarque : une seule des méthodes api.authentication.setUserByConnection ou api.authentication.setUserById doit être appelée par l’action Custom Token Exchange.

connection_name · string

Nom de la connexion dans laquelle l’utilisateur doit être enregistré.

user_attributes · setuserbyconnectionuserattributes

Les attributs du profil de l’utilisateur, y compris user_id et, éventuellement, d’autres attributs comme email, name, etc.

Le champ user_id est requis et doit correspondre à l’identifiant unique de l’utilisateur dans la connexion; il servira à déterminer si l’utilisateur existe ou s’il doit être créé. Pour un utilisateur existant, ce user_id se trouve dans le tableau identities du profil utilisateur normalisé.

Si l’utilisateur existe déjà, les attributs utilisateur suivants ne peuvent pas être mis à jour : email, email_verified, phone, phone_verified, username. S’ils ne correspondent pas à ceux de l’utilisateur existant, une erreur sera renvoyée.

Masquer Propriétés de user_attributes

email · string · optional

Le courriel de l’utilisateur.

email_verified · boolean · optional

Indique si cette adresse courriel est vérifiée (true) ou non (false). L’utilisateur recevra un courriel de vérification après sa création si email_verified vaut false ou n’est pas spécifié.

family_name · string · optional

Le ou les noms de famille de l’utilisateur.

given_name · string · optional

Le ou les prénoms de l’utilisateur.

name · string · optional

Le nom complet de l’utilisateur.

nickname · string · optional

Le surnom de l’utilisateur.

phone_number · string · optional

Le numéro de téléphone de l’utilisateur (conformément à la recommandation E.164).

phone_verified · boolean · optional

Indique si ce numéro de téléphone a été vérifié (true) ou non (false).

picture · string · optional

URI pointant vers l’image de l’utilisateur.

user_id · string

L’identifiant unique de l’utilisateur dans la connexion.

username · string · optional

Le nom d’utilisateur.

verify_email · boolean · optional

Indique si l’utilisateur recevra un courriel de vérification après sa création (true) ou non (false). Remplace le comportement du paramètre email_verified.

options · setuserbyconnectionoptions

Options permettant de contrôler le comportement de la commande setUserByConnection.

• creationBehavior - Comportement à appliquer si aucun utilisateur avec le user_id spécifié n’existe dans la connexion. Peut être ‘create_if_not_exists’, ce qui entraîne la création d’un nouvel utilisateur à partir des attributs utilisateur fournis; ou ‘none’, auquel cas aucun utilisateur n’est créé et une erreur est renvoyée si aucun utilisateur n’existe.

• updateBehavior - Comportement à appliquer si un utilisateur avec le user_id spécifié existe déjà dans la connexion. Peut être ‘replace’, ce qui remplace les attributs de l’utilisateur existant par les attributs utilisateur spécifiés; ou ‘none’, ce qui signifie que l’utilisateur existant ne sera pas modifié.

Masquer propriétés des options

creationBehavior · string

Comportement à appliquer si aucun utilisateur avec le user_id spécifié n’existe dans la connexion. Peut être ‘create_if_not_exists’, ce qui entraîne la création d’un nouvel utilisateur à partir des attributs utilisateur fournis; ou ‘none’, auquel cas aucun utilisateur n’est créé et une erreur est renvoyée si aucun utilisateur n’existe.

Valeurs autorisées : create_if_not_exists, none

updateBehavior · string

Comportement à appliquer si un utilisateur avec le user_id spécifié existe déjà dans la connexion. Peut être ‘replace’, ce qui remplace les attributs de l’utilisateur existant par les attributs utilisateur spécifiés; ou ‘none’, ce qui signifie que l’utilisateur existant ne sera pas modifié.

Valeurs autorisées : none, replace

Set user by connection with full profile attributes

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre stratégie d'autorisation sur l'utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l'utilisateur pour la transaction
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: subject_token.email_verified,
      phone_number: subject_token.phone_number,
      phone_verified: subject_token.phone_number_verified,
      username: subject_token.preferred_username,
      name: subject_token.name,
      given_name: subject_token.given_name,
      family_name: subject_token.family_name,
      nickname: subject_token.nickname,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};

Create a user without verifying email

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // Créer un utilisateur sans vérifier le courriel
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: false,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};

​

api.authentication.setOrganization(organization_id_or_name)

Définit l’organisation pour l’utilisateur associé à l’échange de jetons.

organization_id_or_name · string

L’ID ou le nom de l’organisation à associer à l’utilisateur.

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre stratégie d'autorisation sur l'utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l'organisation pour la transaction
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. Définir l'utilisateur pour la transaction. Vous pouvez aussi utiliser setUserByConnection()
  api.authentication.setUserById(subject_token.sub);

  return;
};

​

api.authentication.setActor(actor)

Définit l’acteur pour l’échange de jetons afin de représenter l’entité agissant au nom du sujet. Doit être utilisée avec les commandes setUserById ou SetUserByConnection. L’appel à setActor est facultatif. La réception d’un actor_token dans la requête ne produit pas automatiquement un claim act ; l’Action doit appeler explicitement cette méthode. Les jetons d’actualisation ne sont pas émis lorsqu’un acteur est défini pour la transaction.

actor · actorparams

Objet imbriqué qui représente une chaîne de délégation. Jusqu’à 4 niveaux act supplémentaires sont autorisés (5 acteurs au total, y compris l’acteur racine). Pour chaque niveau, le champ sub est obligatoire ; jusqu’à 5 propriétés personnalisées supplémentaires (valeurs de type chaîne, booléen ou nombre) peuvent être fournies.

Masquer propriétés d’actor

sub · string

act · dictionary · optional

Masquer propriétés d’act

sub · string

act · dictionary · optional

Masquer propriétés d’act

sub · string

act · dictionary · optional

Afficher propriétés d’act

sub · string

act · dictionary · optional

Afficher propriétés d’act

sub · string

act · undefined · optional

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  const actor_token = await validateToken(event.transaction.actor_token, jwksUri);

  // 2. Définir l'acteur pour la transaction
  api.authentication.setActor({ sub: actor_token.sub });

  // 3. Définir l'utilisateur pour la transaction
  api.authentication.setUserById(subject_token.sub);

  return;
};

​

api.user

Demandez des modifications pour l’utilisateur correspondant au jeton du sujet.

​

api.user.setAppMetadata(key, value)

Définit des métadonnées propres à l’application pour l’utilisateur correspondant au jeton du sujet.

key · string

La propriété de métadonnées à définir.

value · unknown

La valeur de la propriété de métadonnées. Elle peut être définie à null pour supprimer la propriété de métadonnées.

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // définir l'utilisateur pour la transaction
  api.authentication.setUserById(subject_token.id);

  // définir le groupe d'utilisateurs selon les informations contenues dans subject_token
  api.user.setAppMetadata('group', subject_token.group);

  return;
};

​

api.user.setUserMetadata(key, value)

Définit les métadonnées générales de l’utilisateur associé au jeton du sujet.

key · string

La propriété de métadonnées à définir.

value · unknown

La valeur de la propriété de métadonnées. Elle peut être définie à null pour supprimer la propriété de métadonnées.

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // définir l'utilisateur pour la transaction
  api.authentication.setUserById(subject_token.id);

  // définir le preferred_locale de l'utilisateur à partir des informations contenues dans le subject_token
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};

​

api.cache

Stocker et récupérer des données qui persistent d’une exécution à l’autre.

​

api.cache.delete(key)

Supprime l’enregistrement correspondant à la valeur mise en cache associée à la clé fournie, s’il existe.

key · string

La clé de l’enregistrement du cache à supprimer.

​

api.cache.get(key)

Récupère une entrée décrivant une valeur mise en cache à la clé fournie, si elle existe. Si une entrée est trouvée, la valeur mise en cache se trouve dans la propriété value de l’objet renvoyé.

key · string

La clé de l’entrée stockée dans le cache.

​

api.cache.set(key, value, options)

Stocke ou met à jour une valeur de chaîne dans le cache pour la clé spécifiée.

Les valeurs stockées dans ce cache ont une portée limitée au Trigger dans lequel elles sont définies. Elles sont soumises aux Actions Cache Limits.

Les valeurs stockées de cette façon auront une durée de vie pouvant aller jusqu’à celle indiquée par ttl ou expires_at. Si aucune durée de vie n’est spécifiée, une durée de vie par défaut de 15 minutes sera utilisée. Les durées de vie ne peuvent pas dépasser la durée maximale indiquée dans Actions Cache Limits.

Important : Ce cache est conçu pour des données éphémères de courte durée. Des éléments peuvent ne pas être disponibles dans des transactions ultérieures, même s’ils sont encore dans leur durée de vie spécifiée.

key · string

La clé de l’enregistrement à stocker.

value · string

La valeur de l’enregistrement à stocker.

options · cachesetoptions · optional

Options permettant d’ajuster le comportement du cache.

Masquer propriétés de l’objet options

expires_at · number · optional

L’heure d’expiration absolue, en millisecondes depuis l’époque Unix. Bien que les enregistrements mis en cache puissent être évincés plus tôt, ils ne seront jamais conservés au-delà de la valeur expires_at fournie.

Remarque : Cette valeur ne doit pas être fournie si une valeur a aussi été fournie pour ttl. Si les deux options sont fournies, la date d’expiration la plus rapprochée des deux sera utilisée.

ttl · number · optional

La durée de vie de cette entrée de cache, en millisecondes. Bien que les valeurs mises en cache puissent être évincées plus tôt, elles ne seront jamais conservées au-delà de la valeur ttl fournie.

Remarque : Cette valeur ne doit pas être fournie si une valeur a aussi été fournie pour expires_at. Si les deux options sont fournies, la date d’expiration la plus rapprochée des deux sera utilisée.