Aller au contenu

Vérifier un jeton côté serveur

Vérifier la signature, l'émetteur, l'expiration et l'application d'un jeton Keycloak dans votre backend, sans coder d'URL Keycloak.

GuideDéveloppeur
Durée
15 min
Voir en Markdown

Quand votre backend reçoit un jeton, par exemple d'une application mobile ou d'un autre de vos services, il doit le vérifier avant de lui faire confiance. Ce guide vérifie un jeton d'accès Keycloak avec les clés publiques de l'instance (JWKS), puis contrôle qu'il a été émis pour votre application.

Avant de commencer

  • Le nom d'hôte de votre front est un hôte IAM de l'environnement : votre backend l'utilise pour retrouver l'émetteur attendu auprès de Discovery.

  • Node.js 20 ou plus récent, et la bibliothèque jose :

    Bash
    npm install jose

Retrouver l'émetteur et le client attendus

Au démarrage, demandez à Discovery l'URL de connexion de votre front et déduisez-en l'émetteur (iss) et l'identifiant client (azp) attendus. Votre backend ne contient ainsi aucune URL Keycloak.

expected-issuer.tsTypeScript
export interface Expected {
  issuer: string; // https://<instance>/realms/<realm>
  clientId: string;
}

export async function resolveExpected(publicUrl: string): Promise<Expected> {
  const response = await fetch("https://discovery.wakastart.app/discover/start-login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      host: new URL(publicUrl).host,
      redirectUri: `${publicUrl}/api/auth/callback`,
    }),
  });
  if (!response.ok) throw new Error(`Discovery a répondu ${response.status}`);
  const { keycloakUrl } = (await response.json()) as { keycloakUrl: string };
  const url = new URL(keycloakUrl);
  return {
    issuer: `${url.origin}${url.pathname.replace(/\/protocol\/openid-connect\/auth$/, "")}`,
    clientId: url.searchParams.get("client_id")!,
  };
}

Résultat attendu, pour https://mon-app.exemple.fr en production :

JSON
{ "issuer": "https://auth.wakastart.app/realms/realm-EXNET1", "clientId": "EXAPP1" }

Vérifier le jeton

Vérifiez la signature avec le JWKS de l'émetteur, l'émetteur lui-même et l'expiration, puis l'application destinataire (azp) :

verify-token.tsTypeScript
import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
import type { Expected } from "./expected-issuer";

export function createVerifier(expected: Expected) {
  // Clés publiques de l'instance Keycloak, mises en cache par jose.
  const jwks = createRemoteJWKSet(new URL(`${expected.issuer}/protocol/openid-connect/certs`));

  return async function verify(token: string): Promise<JWTPayload & { email?: string; wenv?: string }> {
    const { payload } = await jwtVerify(token, jwks, {
      issuer: expected.issuer,
      algorithms: ["RS256"],
      clockTolerance: 30,
    });
    if (payload.azp !== expected.clientId) {
      throw new Error("Jeton émis pour une autre application");
    }
    return payload;
  };
}

Utilisez-le dans un middleware Express :

server.tsTypeScript
import express from "express";
import { resolveExpected } from "./expected-issuer";
import { createVerifier } from "./verify-token";

const expected = await resolveExpected(process.env.PUBLIC_URL!);
const verify = createVerifier(expected);
const app = express();

app.use("/api", async (req, res, next) => {
  const token = req.headers.authorization?.replace(/^Bearer /, "");
  if (!token) return res.status(401).json({ error: "missing_token" });
  try {
    res.locals.user = await verify(token);
    next();
  } catch {
    res.status(401).json({ error: "invalid_token" });
  }
});

app.get("/api/profil", (_req, res) => res.json({ sub: res.locals.user.sub, email: res.locals.user.email }));
app.listen(3000);

Ne contrôlez pas aud : dans les jetons d'accès Keycloak, il ne désigne pas votre application. C'est azp qui porte l'identifiant client.

Important

La signature prouve l'identité, pas les droits. Avant d'autoriser une action, lisez les droits de l'utilisateur dans GET /api/me (voir Charger le contexte utilisateur) : c'est aussi ce qui confirme que l'utilisateur a toujours accès à l'application dans cet environnement.

Et le jeton enrichi ?

Le jeton enrichi est signé par Wakastart, mais ses clés de vérification ne sont pas publiées pour les applications. Ne prenez pas de décision d'autorisation sur son contenu décodé : faites-le vérifier par l'API publique en l'envoyant dans l'en-tête x-enriched-token, par exemple sur GET /api/me, ou vérifiez le jeton Keycloak comme indiqué dans ce guide.

Vérifier le résultat

  1. Appelez votre route avec un jeton valide :

    Bash
    curl -s https://mon-app.exemple.fr/api/profil -H "Authorization: Bearer $ACCESS_TOKEN"

    Réponse attendue :

    JSON
    { "sub": "4f1c2a9e-7d3b-4b8e-9a51-2c6e0f8d1b77", "email": "claire.martin@exemple.fr" }
  2. Rappelez-la avec un jeton d'une autre application ou d'un autre environnement. Réponse attendue : 401 et { "error": "invalid_token" }.

Voir aussi