Saltar al contenido principal
El objeto API del trigger custom-token-exchange de Actions incluye:

​
api.access

Modifica el acceso a la solicitud de intercambio de tokens, por ejemplo, rechazándola.

​
api.access.deny(code, reason)

Marca el intercambio de tokens actual como denegado. Si la solicitud se deniega debido a un token de sujeto no válido, recomendamos usar api.access.rejectInvalidSubjectToken en su lugar para distinguir entre intentos de fuerza bruta sobre el token de sujeto y otros motivos para denegar la solicitud.
​
code
string
El código de error que justifica el rechazo del intercambio de tokens. Puede ser invalid_request, server_error o cualquier código personalizado.
​
reason
string
Una explicación en lenguaje claro de por qué se rechaza la solicitud de intercambio de tokens.
exports.onExecuteCustomTokenExchange = async (event, api) => {

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

  // 2. Aplicar la política de autorización al usuario
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // si el usuario está autorizado, continuar según se indica aquí

};

​
api.access.rejectInvalidSubjectToken(reason)

Marca como no válido el token de sujeto proporcionado en la solicitud. Esto hará que la solicitud se rechace con el código de error “invalid_request”. Esto indicará a las funciones de Attack Protection que se ha proporcionado un token de sujeto no válido, para que puedan aplicarse protecciones destinadas a evitar ataques de fuerza bruta contra el token de sujeto.
​
reason
string
Una explicación en lenguaje claro de por qué se rechaza la solicitud de intercambio de tokens.
exports.onExecuteCustomTokenExchange = async (event, api) => {

  try {
    // Validar subject_token
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // establecer el usuario para la transacción
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // Si el problema es específicamente que el subject_token no es válido
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // si hay cualquier otro error inesperado, lanzar un error de servidor
      throw error;
    }
  }

};

​
api.authentication

Indica el resultado de la autenticación del token de sujeto para especificar el usuario para el que se emitirán los tokens.

​
api.authentication.setUserById(user_id)

Indica el usuario correspondiente al subject_token proporcionando el userId. La solicitud de intercambio de tokens emitirá tokens para este usuario. Debe ser un usuario existente. Nota: La acción Custom Token Exchange debe llamar a exactamente una de estas opciones: api.authentication.setUserByConnection o api.authentication.setUserById.
​
user_id
string
El ID del usuario; debe corresponder a un usuario existente.
exports.onExecuteCustomTokenExchange = async (event, api) => {

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

  // 2. Aplicar la política de autorización al usuario
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Establecer el usuario para la transacción
  api.authentication.setUserById(subject_token.sub);

  return;
};

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

Indica el usuario correspondiente al subject_token proporcionando una conexión y los atributos del usuario. La solicitud de intercambio de tokens emitirá tokens para este usuario. Puede tratarse de un usuario existente o de uno nuevo. Si el usuario no existe, se creará. La propiedad user_id de user_profile se utilizará para determinar si el usuario ya existe. Nota: La acción Custom Token Exchange debe llamar exactamente a una de estas opciones: api.authentication.setUserByConnection o api.authentication.setUserById.
​
connection_name
string
Nombre de la conexión en la que debe almacenarse el usuario.
​
user_attributes
setuserbyconnectionuserattributes
Los atributos del perfil del usuario, incluidos user_id y, opcionalmente, otros atributos como email, name, etc.El campo user_id es obligatorio y debe ser el identificador único del usuario dentro de la conexión; se utilizará para determinar si el usuario existe o si debe crearse. En el caso de usuarios existentes, este user_id puede encontrarse inspeccionando el array identities del perfil de usuario normalizado.Si el usuario ya existe, no se pueden actualizar los siguientes atributos del usuario: email, email_verified, phone, phone_verified, username. Si no coinciden con el usuario existente, se devolverá un error.
​
options
setuserbyconnectionoptions
Opciones para controlar el comportamiento del comando setUserByConnection.
  • creationBehavior - comportamiento que se aplicará si no existe ningún usuario con el user_id especificado en la conexión. Puede ser ‘create_if_not_exists’, lo que hará que se cree un nuevo usuario con los atributos de usuario proporcionados; o ‘none’, lo que hará que no se cree ningún usuario y que se devuelva un error si no existe ningún usuario.
  • updateBehavior - comportamiento que se aplicará si un usuario con el user_id especificado ya existe en la conexión. Puede ser ‘replace’, lo que hará que los atributos del usuario existente se reemplacen por los atributos de usuario especificados; o ‘none’, lo que significa que el usuario existente no se modificará.
Set user by connection with full profile attributes
exports.onExecuteCustomTokenExchange = async (event, api) => {

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

  // 2. Aplicar la política de autorización al usuario
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Establecer el usuario para la transacción
  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) => {

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

  // Crear un usuario sin verificar el correo electrónico
  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)

Establece la organización del usuario asociado al intercambio de tokens.
​
organization_id_or_name
string
El id o el nombre de la organización que se establecerá para el usuario.
exports.onExecuteCustomTokenExchange = async (event, api) => {

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

  // 2. Aplicar la política de autorización al usuario
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Establecer la organización para la transacción
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. Establecer el usuario para la transacción. También puede usar setUserByConnection()
  api.authentication.setUserById(subject_token.sub);

  return;
};

​
api.authentication.setActor(actor)

Establece el actor para el intercambio de tokens a fin de representar a la entidad que actúa en nombre del sujeto. Debe usarse junto con los comandos setUserById o SetUserByConnection. Llamar a setActor es opcional. Recibir un actor_token en la solicitud no genera automáticamente un claim act; la Action debe llamar explícitamente a este método. No se emiten Tokens de actualización cuando se establece un actor para la transacción.
​
actor
actorparams
Un objeto anidado que representa una cadena de delegación. Se permiten hasta 4 niveles adicionales de act (5 actores en total, incluido el actor raíz). Para cada nivel, el campo sub es obligatorio; se pueden proporcionar hasta 5 propiedades personalizadas adicionales (valores de tipo cadena, booleano o numérico).
exports.onExecuteCustomTokenExchange = async (event, api) => {

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

  // 2. Establecer el actor para la transacción
  api.authentication.setActor({ sub: actor_token.sub });

  // 3. Establecer el usuario para la transacción
  api.authentication.setUserById(subject_token.sub);

  return;
};

​
api.user

Solicita cambios en el usuario correspondiente al token de sujeto.

​
api.user.setAppMetadata(key, value)

Establece metadatos específicos de la aplicación para el usuario asociado al token de sujeto.
​
key
string
La propiedad de metadatos que se va a establecer.
​
value
unknown
El valor de la propiedad de metadatos. Se puede establecer en null para eliminar la propiedad de metadatos.
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Validar subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // establecer el usuario para la transacción
  api.authentication.setUserById(subject_token.id);

  // establecer el grupo de usuario según la información contenida en subject_token
  api.user.setAppMetadata('group', subject_token.group);

  return;
};

​
api.user.setUserMetadata(key, value)

Establece metadatos generales para el usuario correspondiente al token de sujeto.
​
key
string
La propiedad de metadatos que se va a establecer.
​
value
unknown
El valor de la propiedad de metadatos. Puede establecerse en null para eliminar la propiedad de metadatos.
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Validar subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // establecer el usuario para la transacción
  api.authentication.setUserById(subject_token.id);

  // establecer preferred_locale del usuario según la información contenida en subject_token
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};

​
api.cache

Permite almacenar y recuperar datos que persisten entre ejecuciones.

​
api.cache.delete(key)

Elimina el registro que describe un valor almacenado en caché en la clave proporcionada, si existe.
​
key
string
La clave del registro de caché que se eliminará.

​
api.cache.get(key)

Recupera un registro que describe un valor almacenado en caché en la clave proporcionada, si existe. Si se encuentra un registro, el valor almacenado en caché está disponible en la propiedad value del objeto devuelto.
​
key
string
La clave del registro almacenado en la caché.

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

Almacena o actualiza un valor de tipo cadena en la caché con la clave especificada. Los valores almacenados en esta caché se limitan al Trigger en el que se establecen. Están sujetos a los límites de caché de Actions. Los valores almacenados de esta forma tendrán una duración de hasta los valores ttl o expires_at especificados. Si no se especifica ninguna duración, se usará una duración predeterminada de 15 minutos. La duración no puede superar el máximo indicado en límites de caché de Actions. Importante: Esta caché está diseñada para datos efímeros y de corta duración. Es posible que los elementos no estén disponibles en transacciones posteriores, aunque sigan dentro de la duración especificada.
​
key
string
La clave del registro que se almacenará.
​
value
string
El valor del registro que se almacenará.
​
options
cachesetoptions
optional
Opciones para ajustar el comportamiento de la caché.