Crear un script de reclamos personalizados de token

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

Navega a Consola > JWT personalizado.
Hay dos tipos diferentes de tokens de acceso para los que 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 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 que quieras 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 personalizados de token solo está disponible para:

Usuarios de Logto OSS
Inquilinos de Logto Cloud con entorno de desarrollo
Inquilinos de pago de Logto Cloud con entorno de producción (incluyendo Inquilinos Pro y Enterprise)

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 personalizados de token. El script debe ser una función de JavaScript que devuelva un objeto de reclamos personalizados.

Página de detalles de reclamos personalizados de token

Paso 1: Editar el script

Utiliza el editor de código en el lado izquierdo para modificar el script. Se proporciona una función getCustomJwtClaims predeterminada que retorna un objeto vacío para que puedas comenzar. Puedes modificar la función para que retorne un objeto con 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 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 los 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 de 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 identificador único del JWT	`string`
`aud`	La audiencia (Audience) del token	`string`
`scope`	Los alcances (Scopes) del token	`string`
`clientId`	El id del cliente del token	`string`
`accountId`	El id de 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 identificador único del JWT	`string`
`aud`	La audiencia (Audience) del token	`string`
`scope`	Los alcances (Scopes) 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 la concesión relevantes para el proceso de autorización (Authorization) actual.

Objeto de datos de usuario Para el token de acceso de usuario, Logto proporciona un contexto adicional de datos de usuario para que puedas acceder. El objeto de datos de usuario contiene todos los datos del perfil del usuario y los datos de membresía de organización (Organization) que puedas necesitar para configurar los reclamos personalizados. Consulta Usuarios y Organizaciones para más detalles.
Objeto de datos de concesión Para el token de acceso de usuario concedido por intercambio de token de suplantación, Logto proporciona un contexto adicional de datos de concesión para que puedas acceder. El objeto de datos de concesión contiene el contexto personalizado del token de sujeto. Consulta Suplantación de usuario para más detalles.

Objeto de datos de interacción de usuario Para un token de acceso de usuario dado, puede haber casos en los que necesites acceder a los detalles de interacción del usuario para la sesión de autorización (Authorization) actual. Por ejemplo, podrías necesitar recuperar la identidad de SSO empresarial utilizada por el usuario para iniciar sesión. Este objeto de datos de interacción de usuario contiene los datos de interacción más recientes enviados por el usuario, incluyendo:

Propiedad	Descripción	Tipo
`interactionEvent`	El evento de interacción de la interacción actual del usuario	`SignIn` o `Register`
`userId`	El id de usuario de la interacción actual del usuario	`string`
`verificationRecords`	Una lista de registros de verificación enviados por el usuario para identificar y verificar su identidad durante las interacciones.	`VerificationRecord[]`

Tipo de registro de verificación:

// VerificationType.Password
{
  id: string;
  type: 'Password';
  identifier: {
    type: 'username' | 'email' | 'phone' | 'userId';
    value: string;
  }
  verified: boolean;
}

// VerificationType.EmailVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'EmailVerificationCode';
  identifier: {
    type: 'email';
    value: string;
  }
}

// VerificationType.PhoneVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'PhoneVerificationCode';
  identifier: {
    type: 'phone';
    value: string;
  }
}

// VerificationType.Social
{
  id: string;
  type: 'Social';
  connectorId: string;
  socialUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    rawData?: Record<string, unknown> | undefined;
  } | undefined;
}

// VerificationType.EnterpriseSso
{
  id: string;
  type: 'EnterpriseSso';
  connectorId: string;
  enterpriseUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    [key: string]?: unknown;
  } | undefined;
  issuer?: string | undefined;
}

// VerificationType.Totp (MFA)
{
  id: string;
  type: 'Totp';
  userId: string;
  verified: boolean;
}

// VerificationType.WebAuthn (MFA)
{
  id: string;
  type: 'WebAuthn';
  userId: string;
  verified: boolean;
}

// VerificationType.BackupCode (MFA)
{
  id: string;
  type: "BackupCode";
  userId: string;
  code?: string | undefined;
}

// VerificationType.OneTimeToken
{
  id: string;
  type: "OneTimeToken";
  verified: boolean;
  identifier: {
    type: "email";
    value: string;
  };
  oneTimeTokenContext?: {
    jitOrganizationIds?: string[] | undefined;
  } | undefined;
}

nota:

Puede haber múltiples registros de verificación en el objeto de datos de interacción de usuario, especialmente cuando el usuario ha pasado por varios procesos de inicio de sesión o registro.

Por ejemplo, el usuario ha iniciado sesión usando un registro de verificación Social, luego ha vinculado una nueva dirección de correo electrónico mediante un registro de verificación EmailVerificationCode, y luego ha verificado el estado de MFA con un registro de verificación Totp. En este caso, es posible que debas manejar todos los registros de verificación en tu script.

Cada tipo de registro de verificación solo estará presente una vez en el objeto de datos de interacción de usuario.

environmentVariables

Utiliza la sección Configurar variables de entorno en la parte derecha 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 quieras codificar directamente 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 utilitarias que puedes usar en tu script para un control de acceso adicional sobre el proceso de emisión del token. 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 del token con un mensaje personalizado. Puedes usar esta función para aplicar validaciones de acceso adicionales sobre el proceso de emisión del token.

Paso 3: Obtener datos externos

Puedes usar la función incorporada de node fetch 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 del token. Asegúrate de que la API externa sea lo suficientemente confiable y rápida para cumplir con tus requisitos.

Además:

Maneja correctamente los errores y los tiempos de espera en tu script para evitar que el proceso de emisión del token 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 simulada del token y el contexto de datos de usuario para las pruebas.

Haz clic en Ejecutar prueba en la esquina superior derecha del editor para ejecutar el script con los datos simulados. El resultado del script se mostrará en el panel Resultado de la prueba.

nota:

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

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

Implementar la función getCustomJwtClaims()​

Paso 1: Editar el script​

Paso 2: Parámetros de entrada​

token​

context (Solo disponible para token de acceso de usuario)​

environmentVariables​

api​

Paso 3: Obtener datos externos​

Paso 4: Probar el script​

Implementar la función `getCustomJwtClaims()`

Paso 1: Editar el script

Paso 2: Parámetros de entrada

token

context (Solo disponible para token de acceso de usuario)

environmentVariables

api

Paso 3: Obtener datos externos

Paso 4: Probar el script