Aller au contenu principal

Comment valider les jetons d’accès dans votre service API ou backend

La validation des jetons d’accès (Access tokens) est une étape essentielle pour appliquer le contrôle d’accès basé sur les rôles (RBAC) dans Logto. Ce guide vous explique comment vérifier les JWT émis par Logto dans votre backend / API, en contrôlant la signature, l’émetteur (Issuer), l’audience (Audience), l’expiration, les permissions (Portées / Scopes) et le contexte d’organisation.

Avant de commencer​

Étape 1 : Initialiser les constantes et utilitaires​

Définissez les constantes et utilitaires nécessaires dans votre code pour gérer l’extraction et la validation du jeton. Une requête valide doit inclure un en-tête Authorization sous la forme 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('L’en-tête Authorization est manquant', 401);
  }

  if (!authorization.startsWith(bearerPrefix)) {
    throw new AuthorizationError(
      `L’en-tête Authorization doit commencer par "${bearerPrefix}"`,
      401
    );
  }

  return authorization.slice(bearerPrefix.length);
}

Étape 2 : Récupérer les informations sur votre tenant Logto​

Vous aurez besoin des valeurs suivantes pour valider les jetons émis par Logto :

  • URI JSON Web Key Set (JWKS) : L’URL vers les clés publiques de Logto, utilisée pour vérifier la signature des JWT.
  • Émetteur (Issuer) : La valeur attendue de l’émetteur (URL OIDC de Logto).

Commencez par trouver l’endpoint de votre tenant Logto. Vous pouvez le trouver à différents endroits :

  • Dans la Console Logto, sous Paramètres → Domaines.
  • Dans les paramètres de toute application configurée dans Logto, Paramètres → Endpoints & Credentials.

Récupérer depuis l’endpoint de découverte OpenID Connect​

Ces valeurs peuvent être récupérées depuis l’endpoint de découverte OpenID Connect de Logto :

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

Voici un exemple de réponse (autres champs omis pour la clarté) :

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

Puisque Logto ne permet pas de personnaliser l’URI JWKS ou l’émetteur, vous pouvez coder ces valeurs en dur dans votre code. Cependant, cela n’est pas recommandé pour les applications en production car cela peut augmenter la maintenance si la configuration change à l’avenir.

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

Étape 3 : Valider le jeton et les permissions​

Après avoir extrait le jeton et récupéré la configuration OIDC, validez les éléments suivants :

  • Signature : Le JWT doit être valide et signé par Logto (via JWKS).
  • Émetteur (Issuer) : Doit correspondre à l’émetteur de votre tenant Logto.
  • Audience (Audience) : Doit correspondre à l’indicateur de ressource API enregistré dans Logto, ou au contexte d’organisation si applicable.
  • Expiration : Le jeton ne doit pas être expiré.
  • Permissions (Portées / Scopes) : Le jeton doit inclure les portées requises pour votre API / action. Les portées sont des chaînes séparées par des espaces dans la revendication scope.
  • Contexte d’organisation : Si vous protégez des ressources API au niveau organisation, validez la revendication organization_id.

Voir JSON Web Token pour en savoir plus sur la structure et les revendications des JWT.

À vérifier selon chaque modèle de permission​

Les revendications et règles de validation diffèrent selon le modèle de permission :

Modèle de permissionRevendication Audience (aud)Revendication Organisation (organization_id)Portées (permissions) à vérifier (scope)
Ressources API globalesIndicateur de ressource APINon présentPermissions de ressource API
Permissions d’organisation (non-API)urn:logto:organization:<id> (le contexte d’organisation est dans aud)Non présentPermissions d’organisation
Ressources API au niveau organisationIndicateur de ressource APIID de l’organisation (doit correspondre à la requête)Permissions de ressource API

Pour les permissions d’organisation non-API, le contexte d’organisation est représenté par la revendication aud (par exemple, urn:logto:organization:abc123). La revendication organization_id n’est présente que pour les jetons de ressource API au niveau organisation.
astuce:

Validez toujours à la fois les permissions (portées) et le contexte (audience, organisation) pour des APIs multi-tenant sécurisées.

Ajouter la logique de validation​

Nous utilisons jose dans cet exemple pour valider le JWT. Installez-le si ce n'est pas déjà fait :

npm install jose

Ou utilisez votre gestionnaire de paquets préféré (par exemple, pnpm ou yarn).

Commencez par ajouter ces utilitaires partagés pour gérer la validation du 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 {
  // Implémentez ici votre logique de vérification basée sur le modèle de permission
  // Ceci sera montré dans la section sur les modèles de permission ci-dessous
}

Ensuite, implémentez le middleware pour vérifier le jeton d’accès (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';

// Étendre l’interface Request d’Express pour inclure 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);

    // Stocker les infos d’auth dans la requête pour un usage générique
    req.auth = createAuthInfo(payload);

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

Selon votre modèle de permission, implémentez la logique de vérification appropriée dans jwt-validator.ts :

jwt-validator.ts
function verifyPayload(payload: JWTPayload): void {
  // Vérifier que la revendication audience correspond à votre indicateur de ressource API
  const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
  if (!audiences.includes('https://your-api-resource-indicator')) {
    throw new AuthorizationError('Audience invalide');
  }

  // Vérifier les portées requises pour les ressources API globales
  const requiredScopes = ['api:read', 'api:write']; // Remplacez par vos portées requises
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  if (!requiredScopes.every((scope) => scopes.includes(scope))) {
    throw new AuthorizationError('Portée insuffisante');
  }
}

Étape 4 : Appliquer le middleware à votre API​

Appliquez le middleware à vos routes API protégées.

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

const app = express();

app.get('/api/protected', verifyAccessToken, (req, res) => {
  // Accédez directement aux informations d'authentification depuis req.auth
  res.json({ auth: req.auth });
});

app.get('/api/protected/detailed', verifyAccessToken, (req, res) => {
  // Votre logique de point de terminaison protégé
  res.json({
    auth: req.auth,
    message: 'Données protégées accessibles avec succès',
  });
});

app.listen(3000);

Étape 5 : Tester votre implémentation​

Testez votre API avec des jetons valides et invalides pour vérifier :

  • Les jetons valides passent et donnent accès.
  • Retournez 401 Unauthorized pour les jetons invalides / manquants. Retournez 403 Forbidden pour les jetons valides qui n’ont pas les permissions ou le contexte requis.
Personnaliser les revendications de jeton JSON Web Token (JWT)

OpenID Connect Discovery

 RFC 8707 : Indicateurs de ressource