Crear un script personalizado de token de acceso

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 que puedes personalizar los reclamos del token de acceso:

   • Token de acceso de usuario: El token de acceso emitido para los 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 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 del 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 del token. El script debe ser una función de JavaScript que devuelva un objeto de reclamos personalizados.

Paso 1: Editar el script

Utiliza el editor de código en el lado izquierdo para modificar el script. Se proporciona una función predeterminada getCustomJwtClaims con un valor de retorno de objeto vacío para que comiences. Puedes modificar la función para devolver 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 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 identificador ú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 identificador ú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 la concesión relevantes para el proceso actual de autorización (Authorization).

• Objeto de datos del usuario Para el token de acceso de usuario, Logto proporciona un contexto adicional de datos del usuario para que puedas acceder. 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. Consulta Usuarios y Organizaciones para más detalles.

• Objeto de datos de la organización Para tokens de acceso de organización (un token de acceso solicitado para una organización específica), Logto proporciona la organización objetivo a través de context.organization, para que puedas adjuntar reclamos por organización—por ejemplo, mapear el ID de organización de Logto a un ID interno almacenado en los datos personalizados de la organización. Este objeto de datos solo está presente cuando el token se emite para una organización específica, y contiene:

  Propiedad	Descripción	Tipo
  id	El identificador único de la organización	string
  name	El nombre de la organización	string
  description	La descripción de la organización	string | null
  customData	Los datos personalizados de la organización	Record<string, unknown>

  Consulta Organizaciones para más detalles.

• Objeto de datos de la 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 la concesión para que puedas acceder. El objeto de datos de la 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 del usuario Para un token de acceso de usuario dado, puede haber instancias donde 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 del usuario utilizada para iniciar sesión. Este objeto de datos de interacción del 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 del 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 a través de 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 del 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 confiable y lo suficientemente rápida para cumplir con tus requisitos.

Además:

• Maneja correctamente los errores y el tiempo 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 la parte derecha de la página para modificar la carga útil simulada del token y el contexto de datos del 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 del 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 del token se guardará y aplicará al proceso de emisión del token de acceso.