# 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.

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.

```ts title="expected-issuer.ts"
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`) :

```ts title="verify-token.ts"
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 :

```ts title="server.ts"
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](/v1.0/authentification/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

- [Jetons et sessions](/v1.0/authentification/jetons-et-sessions).
- [Référence : jeton Keycloak](/v1.0/authentification/reference#jeton-keycloak).
