Saltar al contenido principal

Cómo validar tokens de acceso en tu servicio API o backend

Validar los tokens de acceso es una parte crítica para hacer cumplir el control de acceso basado en roles (RBAC) en Logto. Esta guía te guía a través de la verificación de JWTs emitidos por Logto en tu backend / API, comprobando la firma, emisor, audiencia, expiración, permisos (alcances) y contexto de organización.

Antes de comenzar​

Paso 1: Inicializa constantes y utilidades​

Define las constantes y utilidades necesarias en tu código para manejar la extracción y validación del token. Una solicitud válida debe incluir un encabezado Authorization en la forma Bearer <access_token>.

auth-middleware.ts
import { IncomingHttpHeaders } from 'http';

const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
const ISSUER = 'https://your-tenant.logto.app/oidc';

export class AuthInfo {
  constructor(
    public sub: string,
    public clientId?: string,
    public organizationId?: string,
    public scopes: string[] = [],
    public audience: string[] = []
  ) {}
}

export class AuthorizationError extends Error {
  name = 'AuthorizationError';
  constructor(
    message: string,
    public status = 403
  ) {
    super(message);
  }
}

export function extractBearerTokenFromHeaders({ authorization }: IncomingHttpHeaders): string {
  const bearerPrefix = 'Bearer ';

  if (!authorization) {
    throw new AuthorizationError('Authorization header is missing', 401);
  }

  if (!authorization.startsWith(bearerPrefix)) {
    throw new AuthorizationError(`Authorization header must start with "${bearerPrefix}"`, 401);
  }

  return authorization.slice(bearerPrefix.length);
}

Paso 2: Obtén información sobre tu tenant de Logto​

Necesitarás los siguientes valores para validar los tokens emitidos por Logto:

  • URI de JSON Web Key Set (JWKS): La URL de las claves públicas de Logto, utilizada para verificar las firmas de los JWT.
  • Emisor (Issuer): El valor esperado de emisor (la URL OIDC de Logto).

Primero, encuentra el endpoint de tu tenant de Logto. Puedes encontrarlo en varios lugares:

  • En la Consola de Logto, en Configuración → Dominios.
  • En cualquier configuración de aplicación que hayas configurado en Logto, Configuración → Endpoints y Credenciales.

Obtener desde el endpoint de descubrimiento de OpenID Connect​

Estos valores pueden obtenerse desde el endpoint de descubrimiento de OpenID Connect de Logto:

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

Aquí tienes un ejemplo de respuesta (otros campos omitidos por brevedad):

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

Dado que Logto no permite personalizar el URI de JWKS ni el emisor, puedes codificar estos valores directamente en tu código. Sin embargo, esto no se recomienda para aplicaciones en producción, ya que puede aumentar la carga de mantenimiento si alguna configuración cambia en el futuro.

  • JWKS URI: https://<your-logto-endpoint>/oidc/jwks
  • Emisor: https://<your-logto-endpoint>/oidc

Paso 3: Valida el token y los permisos​

Después de extraer el token y obtener la configuración OIDC, valida lo siguiente:

  • Firma: El JWT debe ser válido y estar firmado por Logto (a través de JWKS).
  • Emisor (Issuer): Debe coincidir con el emisor de tu tenant de Logto.
  • Audiencia (Audience): Debe coincidir con el indicador de recurso de la API registrado en Logto, o el contexto de organización si aplica.
  • Expiración: El token no debe estar expirado.
  • Permisos (alcances / scopes): El token debe incluir los alcances requeridos para tu API / acción. Los alcances son cadenas separadas por espacios en el reclamo scope.
  • Contexto de organización: Si proteges recursos de API a nivel de organización, valida el reclamo organization_id.

Consulta JSON Web Token para aprender más sobre la estructura y los reclamos de los JWT.

Qué comprobar según el modelo de permisos​

Los reclamos y reglas de validación difieren según el modelo de permisos:

Modelo de permisosReclamo de audiencia (aud)Reclamo de organización (organization_id)Alcances (permisos) a comprobar (scope)
Recursos de API globalesIndicador de recurso de APINo presentePermisos de recurso de API
Permisos de organización (no-API)urn:logto:organization:<id> (el contexto de organización está en aud)No presentePermisos de organización
Recursos de API a nivel de organizaciónIndicador de recurso de APIID de organización (debe coincidir con la solicitud)Permisos de recurso de API

Para los permisos de organización no-API, el contexto de organización está representado por el reclamo aud (por ejemplo, urn:logto:organization:abc123). El reclamo organization_id solo está presente para tokens de recursos de API a nivel de organización.
tip:

Valida siempre tanto los permisos (alcances) como el contexto (audiencia, organización) para APIs multi-tenant seguras.

Añade la lógica de validación​

Usamos jose en este ejemplo para validar el JWT. Instálalo si aún no lo has hecho:

npm install jose

O utiliza tu gestor de paquetes preferido (por ejemplo, pnpm o yarn).

Primero, añade estas utilidades compartidas para manejar la validación de JWT:

jwt-validator.ts
import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
import { AuthInfo, AuthorizationError } from './auth-middleware.js';

const jwks = createRemoteJWKSet(new URL(JWKS_URI));

export async function validateJwtToken(token: string): Promise<JWTPayload> {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
  });

  verifyPayload(payload);
  return payload;
}

export function createAuthInfo(payload: JWTPayload): AuthInfo {
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  const audience = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];

  return new AuthInfo(
    payload.sub!,
    payload.client_id as string,
    payload.organization_id as string,
    scopes,
    audience
  );
}

function verifyPayload(payload: JWTPayload): void {
  // Implementa aquí tu lógica de verificación basada en el modelo de permisos
  // Esto se mostrará en la sección de modelos de permisos más abajo
}

Luego, implementa el middleware para verificar el token de acceso (Access token):

auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { extractBearerTokenFromHeaders, AuthorizationError } from './auth-middleware.js';
import { validateJwtToken, createAuthInfo } from './jwt-validator.js';

// Extiende la interfaz Request de Express para incluir auth
declare global {
  namespace Express {
    interface Request {
      auth?: AuthInfo;
    }
  }
}

export async function verifyAccessToken(req: Request, res: Response, next: NextFunction) {
  try {
    const token = extractBearerTokenFromHeaders(req.headers);
    const payload = await validateJwtToken(token);

    // Almacena la información de autenticación en la solicitud para uso general
    req.auth = createAuthInfo(payload);

    next();
  } catch (err: any) {
    return res.status(err.status ?? 401).json({ error: err.message });
  }
}

De acuerdo con tu modelo de permisos, implementa la lógica de verificación apropiada en jwt-validator.ts:

jwt-validator.ts
function verifyPayload(payload: JWTPayload): void {
  // Verifica que el claim de audiencia coincida con tu indicador de recurso de API
  const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
  if (!audiences.includes('https://your-api-resource-indicator')) {
    throw new AuthorizationError('Audiencia inválida');
  }

  // Verifica los alcances requeridos para recursos de API globales
  const requiredScopes = ['api:read', 'api:write']; // Reemplaza con tus alcances requeridos
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  if (!requiredScopes.every((scope) => scopes.includes(scope))) {
    throw new AuthorizationError('Alcance insuficiente');
  }
}

Paso 4: Aplica el middleware a tu API​

Aplica el middleware a tus rutas de API protegidas.

app.ts
import express from 'express';
import { verifyAccessToken } from './auth-middleware.js';

const app = express();

app.get('/api/protected', verifyAccessToken, (req, res) => {
  // Accede a la información de autenticación directamente desde req.auth
  res.json({ auth: req.auth });
});

app.get('/api/protected/detailed', verifyAccessToken, (req, res) => {
  // Tu lógica para el endpoint protegido
  res.json({
    auth: req.auth,
    message: 'Datos protegidos accedidos correctamente',
  });
});

app.listen(3000);

Paso 5: Prueba tu implementación​

Prueba tu API con tokens válidos e inválidos para asegurar que:

  • Los tokens válidos pasan y otorgan acceso.
  • Devuelve 401 Unauthorized para tokens inválidos / ausentes. Devuelve 403 Forbidden para tokens válidos que no tienen los permisos o contexto requeridos.
Personalización de reclamos de tokens JSON Web Token (JWT)

OpenID Connect Discovery

 RFC 8707: Indicadores de recurso