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.
- Duration
- 15 min
This page has not been translated yet and is shown in French.
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:Bashnpm 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.
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 :
{ "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) :
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 :
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
-
Appelez votre route avec un jeton valide :
Bashcurl -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" } -
Rappelez-la avec un jeton d'une autre application ou d'un autre environnement. Réponse attendue :
401et{ "error": "invalid_token" }.