Desencadenadores de Actions: custom-token-exchange - objeto API

Información sobre el objeto API del trigger custom-token-exchange de Actions.

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 Action 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 · customtokenexchangesetuserbyconnectionuserattributes

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.

Ocultar propiedades de user_attributes

email · string · optional

El correo electrónico del usuario.

email_verified · boolean · optional

Indica si esta dirección de correo electrónico está verificada (true) o no verificada (false).

family_name · string · optional

Los apellidos del usuario.

given_name · string · optional

El nombre del usuario.

name · string · optional

El nombre completo del usuario.

nickname · string · optional

El apodo del usuario.

phone_number · string · optional

El número de teléfono del usuario (de acuerdo con la recomendación E.164).

phone_verified · boolean · optional

Indica si este número de teléfono ha sido verificado (true) o no (false).

picture · string · optional

Un URI que apunta a la imagen del usuario.

user_id · string

El identificador único del usuario dentro de la conexión.

username · string · optional

El username del usuario.

verify_email · boolean · optional

Indica si el usuario recibirá un correo electrónico de verificación después de la creación (true) o no recibirá ningún correo electrónico (false).

options · customtokenexchangesetuserbyconnectionoptions

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 ya existe en la conexión un usuario con el user_id especificado. Puede ser replace, lo que hace que los atributos del usuario existente se sustituyan por los atributos de usuario especificados; o none, lo que significa que el usuario existente no se modificará.

Ocultar propiedades de options

creationBehavior · string

Comportamiento que se aplicará si no existe ningún usuario con el user_id especificado en la conexión.

Valores permitidos: create_if_not_exists, none

updateBehavior · string

Comportamiento que se aplicará si ya existe en la conexión un usuario con el user_id especificado.

Valores permitidos: none, replace

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).

Ocultar propiedades del actor

sub · string

act · dictionary · optional

Ocultar propiedades de `act`

sub · string

act · dictionary · optional

Ocultar propiedades de `act`

sub · string

act · dictionary · optional

Mostrar propiedades de `act`

sub · string

act · dictionary · optional

Mostrar propiedades de `act`

sub · string

act · undefined · optional

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é.

Ocultar propiedades de options

expires_at · number · optional

La hora absoluta de vencimiento, en milisegundos desde la época Unix. Aunque los registros en caché pueden eliminarse antes, nunca permanecerán más allá del valor expires_at proporcionado.

Nota: No debe proporcionarse este valor si también se proporcionó un valor para ttl. Si se proporcionan ambas opciones, se usará el vencimiento más próximo de las dos.

ttl · number · optional

El valor de tiempo de vida de esta entrada de caché, en milisegundos. Aunque los valores en caché pueden eliminarse antes, nunca permanecerán más allá del valor ttl proporcionado.

Nota: No debe proporcionarse este valor si también se proporcionó un valor para expires_at. Si se proporcionan ambas opciones, se usará el vencimiento más próximo de las dos.