Objet API

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

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

​

api.access

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

​

api.access.deny(code, reason)

Marquez l’échange de jetons actuel comme rejeté.

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

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

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

  // 2. Appliquer votre politique 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');
  }

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

};

Paramètres

Masquer Paramètres

code · string

Le code d’erreur justifiant le rejet de l’échange de jetons. Peut être invalid_request, server_error ou tout code personnalisé

reason · string

Une explication claire du rejet de la demande d’échange de jetons.

​

api.access.rejectInvalidSubjectToken(reason)

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

Cela indiquera aux fonctionnalités de protection contre les attaques qu’un jeton de sujet invalide a été fourni, afin que des mesures de protection contre les attaques par force brute visant le jeton de sujet puissent être appliquées.

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

  try {
    // Valider 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 est précisément que subject_token n’est pas valide
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // s’il survient toute autre erreur inattendue, générer une erreur de serveur
      throw error;
    }
  }

};

Paramètres

Masquer Paramètres

reason · string

Une explication claire du rejet de la requête d’échange de jeton.

​

api.authentication

Indique le résultat de l’authentification du jeton de sujet afin de préciser l’utilisateur auquel les jetons seront attribués.

​

api.authentication.setUserById(user_id)

Indiquez l’utilisateur associé au subject_token en fournissant son userId. La requête d’échange de jetons émettra des jetons pour cet utilisateur. Cet utilisateur doit déjà exister. Remarque : l’Action Custom Token Exchange doit appeler exactement une des méthodes api.authentication.setUserByConnection ou api.authentication.setUserById.

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

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

  // 2. Appliquer votre politique 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;
};

Paramètres

Masquer Paramètres

user_id · string

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

​

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 jetons é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 profil utilisateur servira à déterminer si l’utilisateur existe déjà.

Remarque : exactement une des méthodes api.authentication.setUserByConnection et api.authentication.setUserById doit être appelée par l’Action Custom Token Exchange.

Set user by connection with full profile attributes

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

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

  // 2. Appliquer votre politique 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.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, mais sans faire la vérification du 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;
};

Paramètres

Masquer Paramètres

connection_name · string

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

user_attributes · customtokenexchangesetuserbyconnectionuserattributes

Les attributs du profil de l’utilisateur, y compris user_id, ainsi que, facultativement, d’autres attributs comme l’adresse courriel, le nom, etc.

Le champ user_id est requis et doit être l’identifiant unique de l’utilisateur au sein de la connexion ; il sert à déterminer si l’utilisateur existe ou doit être créé. Pour les utilisateurs existants, ce user_id se trouve en examinant l’array 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 est renvoyée.

Afficher propriétés de user_attributes

email · string

L’adresse courriel de l’utilisateur. Facultatif.

email_verified · boolean

Indique si cette adresse courriel est vérifiée (true) ou non vérifiée (false). Facultatif.

family_name · string

Le ou les noms de famille de l’utilisateur. Facultatif.

given_name · string

Le ou les prénoms de l’utilisateur. Facultatif.

name · string

Le nom complet de l’utilisateur. Facultatif.

nickname · string

Le surnom de l’utilisateur. Facultatif.

phone_number · string

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

phone_verified · boolean

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

picture · string

Un URI pointant vers l’image de l’utilisateur. Facultatif.

user_id · string

L’identifiant unique de l’utilisateur au sein de la connexion.

username · string

Le nom d’utilisateur de l’utilisateur. Facultatif.

verify_email · boolean

Indique si l’utilisateur recevra un courriel de vérification après sa création (true) ou ne recevra aucun courriel (false). Facultatif.

options · customtokenexchangesetuserbyconnectionoptions

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

• creationBehavior - comportement à appliquer si aucun utilisateur ayant le user_id spécifié n’existe dans la connexion. Peut être ‘create_if_not_exists’, ce qui crée un nouvel utilisateur à l’aide des attributs utilisateur fournis ; ou ‘none’, ce qui empêche la création d’un utilisateur et renvoie une erreur si aucun utilisateur n’existe.

• updateBehavior - comportement à appliquer si un utilisateur ayant 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 n’est pas modifié.

Afficher propriétés des options

creationBehavior · string

Comportement à appliquer si aucun utilisateur ayant le user_id spécifié n’existe dans la connexion. Valeurs autorisées : create_if_not_exists, none

updateBehavior · string

Comportement à appliquer si un utilisateur ayant le user_id spécifié existe déjà dans la connexion. Valeurs autorisées : none, replace

​

api.authentication.setOrganization(organization_id_or_name)

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

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

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

  // 2. Appliquer votre politique 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’organisation pour la transaction
  api.authentication.setOrganization('org_xS525r979AS33MSf');

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

  return;
};

Paramètres

Masquer Paramètres

organization_id_or_name · string

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

​

api.authentication.setActor(actor)

Définissez l’acteur de l’échange de jetons afin de représenter l’entité qui agit au nom du sujet. Doit être utilisé conjointement avec les commandes setUserById ou SetUserByConnection. L’appel à setActor est facultatif. La réception d’un actor_token dans la requête ne génère pas automatiquement une revendication act ; l’Action doit appeler explicitement cette méthode. Aucun jeton d’actualisation n’est émis lorsqu’un acteur est défini pour la transaction.

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

  // 1. Valider 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 de la transaction
  api.authentication.setActor({ sub: actor_token.sub });

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

  return;
};

Paramètres

Masquer Paramètres

actor · actorparams

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

Afficher propriétés de l’acteur

sub · string

act · dictionary

Facultatif.

Afficher propriétés de act

sub · string

act · dictionary

Facultatif.

Afficher propriétés de act

sub · string

act · dictionary

Facultatif.

Afficher propriétés de act

sub · string

act · dictionary

Facultatif.

Afficher propriétés de act

sub · string

act · dictionary

Facultatif.

​

api.user

Demande des modifications à apporter à l’utilisateur correspondant au jeton de sujet.

​

api.user.setAppMetadata(key, value)

Définissez les métadonnées propres à l’application pour l’utilisateur associé au jeton de sujet.

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Valider 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 de l’utilisateur en fonction des renseignements contenus dans subject_token
  api.user.setAppMetadata('group', subject_token.group);

  return;
};

Paramètres

Masquer Paramètres

key · string

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

value · unknown

La valeur de la propriété de métadonnées. Définissez-la à null pour supprimer cette propriété.

​

api.user.setUserMetadata(key, value)

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

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 preferred_locale de l’utilisateur selon les informations contenues dans subject_token
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};

Paramètres

Masquer Paramètres

key · string

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

value · unknown

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

​

api.cache

Stockez et récupérez des données conservées d’une exécution à l’autre.

​

api.cache.delete(key)

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

Paramètres

Masquer Paramètres

key · string

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

​

api.cache.get(key)

Récupère l’enregistrement décrivant la valeur mise en cache associée à la clé fournie, s’il existe. Si un enregistrement est trouvé, la valeur mise en cache se trouve dans la propriété value de l’objet retourné.

Paramètres

Masquer Paramètres

key · string

La clé de l’enregistrement stocké dans le cache.

​

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

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

Les valeurs stockées dans ce cache sont limitées au Trigger dans lequel elles sont définies. Elles sont soumises aux limites du cache Actions.

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

Important : Ce cache est conçu pour stocker des données éphémères de courte durée. Les éléments pourraient ne pas être accessibles lors de transactions ultérieures, même s’ils n’ont pas encore atteint leur durée de vie prévue.

Paramètres

Masquer Paramètres

key · string

La clé de l’enregistrement à stocker.

value · string

La valeur de l’enregistrement à stocker.

options · cachesetoptions

Options permettant d’ajuster le comportement du cache. Facultatif.

Afficher propriétés des options

expires_at · number

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 également été fournie pour ttl. Si les deux options sont fournies, la date d’expiration la plus rapprochée sera utilisée. Facultatif.

ttl · number

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 également été fournie pour expires_at. Si les deux options sont fournies, la date d’expiration la plus rapprochée sera utilisée. Facultatif.