Crear un script de reclamos de token personalizado

Para añadir reclamos personalizados al token de acceso, necesitas proporcionar un script que devuelva un objeto que contenga esos reclamos. El script debe estar escrito como una función de JavaScript que devuelva un objeto con los reclamos personalizados.

1. Navega a Consola > JWT Personalizado.

2. Hay dos tipos diferentes de tokens de acceso para los cuales puedes personalizar los reclamos del token de acceso:

   • Token de acceso de usuario: El token de acceso emitido para usuarios finales. Por ejemplo, para aplicaciones web o aplicaciones móviles.
   • Token de acceso máquina a máquina: El token de acceso emitido para los servicios o aplicaciones. Por ejemplo, para aplicaciones máquina a máquina.

   Diferentes tipos de tokens de acceso pueden tener diferentes contextos de carga útil del token. Puedes personalizar los reclamos del token para cada tipo de token de acceso por separado.

   Elige cualquier tipo de token de acceso para el cual desees personalizar los reclamos del token y haz clic en el botón Añadir reclamos personalizados para crear un nuevo script.

nota

La función de reclamos de token personalizados solo está disponible para:

• Usuarios de Logto OSS
• Inquilinos de Logto Cloud con entorno de desarrollo
• Inquilinos pagos de Logto Cloud con entorno de producción (incluyendo Inquilinos Pro e Inquilinos Empresariales)

Implementar la función getCustomJwtClaims()

En la página de detalles de JWT Personalizado, puedes encontrar el editor de scripts para escribir tu script de reclamos de token personalizado. El script debe ser una función de JavaScript que devuelva un objeto de reclamos personalizados.

Paso 1: Editar el script

Usa el editor de código en el lado izquierdo para modificar el script. Se proporciona un getCustomJwtClaims predeterminado con un valor de retorno de objeto vacío para que comiences. Puedes modificar la función para devolver un objeto de tus propios reclamos personalizados.

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

Este editor utiliza el servidor de lenguaje JavaScript para proporcionar resaltado de sintaxis básico, autocompletado de código y verificación de errores. El parámetro de entrada está bien tipado y documentado en estilo jsDoc. Puedes usar el IntelliSense del editor para acceder correctamente a las propiedades del objeto de entrada. Puedes encontrar las definiciones detalladas de los parámetros en el lado derecho de la página.

nota

Esta función se exportará como un módulo. Asegúrate de mantener el nombre de la función como getCustomJwtClaims para que el módulo pueda exportar la función correctamente.

Paso 2: Parámetros de entrada

La función getCustomJwtClaims toma un objeto como parámetro de entrada. El objeto de entrada contiene las siguientes propiedades:

token

El objeto de carga útil del token. Este objeto contiene reclamos originales del token y metadatos que puedes necesitar acceder en el script.

Puedes encontrar la definición de tipo detallada del objeto de carga útil del token y del objeto de datos del usuario en el lado derecho de la página. El IntelliSense del editor también te ayudará a acceder correctamente a estas propiedades del objeto de entrada.

• Objeto de datos del token de acceso de usuario

  Propiedad	Descripción	Tipo
  jti	El ID único del JWT	string
  aud	La audiencia del token	string
  scope	Los alcances del token	string
  clientId	El ID del cliente del token	string
  accountId	El ID del usuario del token	string
  expiresWithSession	Si el token expirará con la sesión	boolean
  grantId	El ID de concesión de autenticación actual del token	string
  gty	El tipo de concesión del token	string
  kind	El tipo de token	AccessToken

• Objeto de datos del token de acceso máquina a máquina

  Propiedad	Descripción	Tipo
  jti	El ID único del JWT	string
  aud	La audiencia del token	string
  scope	Los alcances del token	string
  clientId	El ID del cliente del token	string
  kind	El tipo de token	ClientCredentials

context (Solo disponible para token de acceso de usuario)

El objeto de contexto contiene los datos del usuario y los datos de concesión que son relevantes para el proceso de autorización actual.

• Objeto de datos del usuario Para el token de acceso de usuario, Logto proporciona un contexto de datos de usuario adicional para que accedas. El objeto de datos del usuario contiene todos los datos del perfil del usuario y los datos de membresía de la organización que puedas necesitar para configurar los reclamos personalizados. Por favor, consulta Usuarios y Organizaciones para más detalles.
• Objeto de datos de concesión Para el token de acceso de usuario otorgado por intercambio de token de suplantación, Logto proporciona un contexto de datos de concesión adicional para que accedas. El objeto de datos de concesión contiene el contexto personalizado del token del sujeto. Por favor, consulta Suplantación de usuario para más detalles.

environmentVariables

Usa la sección Configurar variables de entorno en el lado derecho para configurar las variables de entorno para tu script. Puedes usar estas variables para almacenar información sensible o datos de configuración que no deseas codificar en el script. Por ejemplo, claves de API, secretos o URLs.

Todas las variables de entorno que configures aquí estarán disponibles en el script. Usa el objeto environmentVariables en el parámetro de entrada para acceder a estas variables.

api

El objeto api proporciona un conjunto de funciones de utilidad que puedes usar en tu script para un control de acceso adicional sobre el proceso de emisión de tokens. El objeto api contiene las siguientes funciones:

api.denyAccess(message?: string): void

La función api.denyAccess() te permite denegar el proceso de emisión de tokens con un mensaje personalizado. Puedes usar esta función para imponer una validación de acceso adicional sobre el proceso de emisión de tokens.

Paso 3: Obtener datos externos

Puedes usar la función incorporada fetch de node para obtener datos externos en tu script. La función fetch es una función basada en promesas que te permite hacer solicitudes HTTP a APIs externas.

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

nota

Ten en cuenta que cualquier obtención de datos externos puede introducir latencia en el proceso de emisión de tokens. Asegúrate de que la API externa sea confiable y lo suficientemente rápida para cumplir con tus requisitos.

Además:

• Maneja el error y el tiempo de espera adecuadamente en tu script para evitar que el proceso de emisión de tokens se bloquee.
• Usa encabezados de autorización adecuados para proteger tu API externa de accesos no autorizados.

Paso 4: Probar el script

Asegúrate de probar tu script antes de guardarlo. Haz clic en la pestaña Contexto de prueba en el lado derecho de la página para modificar la carga útil del token simulado y el contexto de datos del usuario para la prueba.

Haz clic en Ejecutar prueba en la esquina superior derecha del editor para ejecutar el script con los datos simulados. La salida del script se mostrará en el cajón de Resultado de la prueba.

nota

El resultado de la prueba es la salida de la función getCustomJwtClaims con los datos simulados que configuraste ("reclamos de token adicionales" obtenidos después de completar el paso 3 en el diagrama de secuencia). La carga útil real del token y el contexto de datos del usuario serán diferentes cuando el script se ejecute en el proceso de emisión de tokens.

Haz clic en el botón Crear para guardar el script. El script de reclamos de token personalizado se guardará y aplicará al proceso de emisión de tokens de acceso.