Aller au contenu

Intégrer la connexion dans une application serveur

Brancher la connexion par nom d'hôte dans une application Node.js rendue côté serveur, avec Express, PKCE et une session HttpOnly.

GuideDéveloppeur
Durée
30 min
Voir en Markdown

Ce guide branche la connexion Wakastart dans une application rendue côté serveur. Le serveur résout l'URL de connexion par nom d'hôte, garde les jetons dans sa session et ne confie au navigateur qu'un cookie HttpOnly. L'exemple utilise Express ; la logique se transpose telle quelle à Fastify, NestJS ou aux routes serveur de Next.js.

Avant de commencer

  • Le nom d'hôte de votre front est déclaré comme hôte IAM de l'environnement visé (voir Déclarer les hôtes IAM et les redirect URIs).
  • Votre serveur répond en HTTPS sur ce nom d'hôte et peut recevoir le chemin /api/auth/callback.
  • Un compte de test a accès à l'application dans cet environnement, avec un profil attribué.
  • Node.js 20 ou plus récent.

Installer les dépendances

  1. Dans le dossier de votre projet, installez Express et sa gestion de session :

    Bash
    npm install express express-session
    npm install --save-dev typescript tsx @types/express @types/express-session
  2. Définissez l'URL publique de votre front dans une variable d'environnement, par exemple dans la configuration de votre service Wakastart (voir Variables et secrets) :

    Bash
    PUBLIC_URL=https://mon-app.exemple.fr
    SESSION_SECRET=une-valeur-aleatoire-longue

    Résultat : votre serveur connaît son propre nom d'hôte. Il ne connaît ni l'instance Keycloak, ni le realm, ni l'identifiant client.

Ajouter la route de connexion

Créez le fichier auth.ts. La route /login génère PKCE et state, appelle Discovery et redirige l'utilisateur :

auth.tsTypeScript
import { Router } from "express";
import { createHash, randomBytes } from "node:crypto";

declare module "express-session" {
  interface SessionData {
    pkce?: { verifier: string; state: string; nonce: string };
    issuer?: string; // https://<instance>/realms/<realm>
    clientId?: string;
    accessToken?: string;
    refreshToken?: string;
    accessTokenExpiresAt?: number;
  }
}

const PUBLIC_URL = process.env.PUBLIC_URL!;
const REDIRECT_URI = `${PUBLIC_URL}/api/auth/callback`;
const DISCOVERY_URL = "https://discovery.wakastart.app";

const random = (bytes: number) => randomBytes(bytes).toString("base64url");

export const auth = Router();

auth.get("/login", async (req, res, next) => {
  try {
    const verifier = random(32);
    const challenge = createHash("sha256").update(verifier).digest("base64url");
    const state = random(16);
    const nonce = random(16);

    const response = await fetch(`${DISCOVERY_URL}/discover/start-login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        host: new URL(PUBLIC_URL).host, // nom d'hôte exact, sans schéma (avec le port pour un hôte local)
        redirectUri: REDIRECT_URI,
        state,
        nonce,
        codeChallenge: challenge,
        codeChallengeMethod: "S256",
      }),
    });
    if (response.status === 404) {
      return res.status(503).send("Connexion indisponible : hôte inconnu de Discovery.");
    }
    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);

    req.session.pkce = { verifier, state, nonce };
    req.session.issuer = `${url.origin}${url.pathname.replace(/\/protocol\/openid-connect\/auth$/, "")}`;
    req.session.clientId = url.searchParams.get("client_id") ?? undefined;
    req.session.save(() => res.redirect(keycloakUrl));
  } catch (err) {
    next(err);
  }
});

Résultat : GET /login redirige vers la page de connexion de votre application, sur l'instance Keycloak de l'environnement.

Recevoir le code et l'échanger

Ajoutez la route de retour au même fichier. Elle contrôle state, puis échange le code auprès de Keycloak :

auth.ts (suite)TypeScript
auth.get("/api/auth/callback", async (req, res, next) => {
  try {
    const { code, state, error } = req.query as Record<string, string | undefined>;
    const pkce = req.session.pkce;
    if (error || !code || !pkce || state !== pkce.state) {
      return res.status(400).send("Retour de connexion invalide.");
    }

    const response = await fetch(`${req.session.issuer}/protocol/openid-connect/token`, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "authorization_code",
        code,
        redirect_uri: REDIRECT_URI,
        client_id: req.session.clientId!,
        code_verifier: pkce.verifier,
      }),
    });
    if (!response.ok) {
      return res.status(401).send(`Échange refusé : ${await response.text()}`);
    }
    const tokens = (await response.json()) as {
      access_token: string;
      refresh_token: string;
      expires_in: number;
    };

    delete req.session.pkce;
    req.session.accessToken = tokens.access_token;
    req.session.refreshToken = tokens.refresh_token;
    req.session.accessTokenExpiresAt = Date.now() + tokens.expires_in * 1000;
    req.session.save(() => res.redirect("/"));
  } catch (err) {
    next(err);
  }
});

Réponse attendue de Keycloak lors de l'échange (extrait) :

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
  "expires_in": 300,
  "refresh_expires_in": 21600,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIn0...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
  "scope": "openid profile email organization"
}

Important

redirect_uri doit être identique, caractère par caractère, à celle envoyée à Discovery et à celle déclarée pour l'hôte IAM : https://<nom d'hôte>/api/auth/callback, sans barre oblique finale.

Monter l'application

Créez server.ts. La session est stockée côté serveur ; le cookie est HttpOnly, Secure et SameSite=Lax (une valeur Strict bloquerait le cookie au retour de Keycloak) :

server.tsTypeScript
import express from "express";
import session from "express-session";
import { auth } from "./auth";

const app = express();
app.set("trust proxy", 1); // le HTTPS est terminé devant votre serveur

app.use(
  session({
    secret: process.env.SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
    cookie: { httpOnly: true, secure: true, sameSite: "lax" },
  }),
);
app.use(auth);

app.get("/", async (req, res) => {
  if (!req.session.accessToken) return res.send('<a href="/login">Se connecter</a>');
  const me = await fetch("https://api.wakastart.app/api/me", {
    headers: { Authorization: `Bearer ${req.session.accessToken}` },
  });
  res.status(me.status).type("json").send(await me.text());
});

app.listen(Number(process.env.PORT ?? 3000));

En production, remplacez le stockage mémoire par défaut d'express-session par un stockage partagé (Valkey, base de données) si votre service a plusieurs réplicas.

Vérifier le résultat

  1. Lancez le serveur : npx tsx server.ts.
  2. Ouvrez https://mon-app.exemple.fr/login et connectez-vous avec le compte de test.

Résultat attendu : la page d'accueil affiche la réponse de GET /api/me, par exemple :

JSON
{
  "wid": "EXUSR1",
  "email": "claire.martin@exemple.fr",
  "firstName": "Claire",
  "lastName": "Martin",
  "isActive": true,
  "adminLevel": "USER",
  "hdsRoles": [],
  "customer": { "wid": "EXCLI1", "name": "Clinique Exemple" },
  "teams": [],
  "profile": {
    "wid": "EXPRF1",
    "name": "Soignant",
    "rights": [{ "code": "dossiers.read", "name": "Lire les dossiers", "category": "Dossiers" }]
  },
  "branding": { "primaryColor": "#0f766e" },
  "createdAt": "2026-09-02T14:05:10.000Z"
}

Dépannage

  • Discovery répond 404 avec "message": "not_found" : le nom d'hôte n'est pas un hôte IAM actif de l'environnement.
  • Keycloak affiche « Invalid parameter: redirect_uri » : l'adresse de retour ne correspond pas à l'hôte IAM.
  • /api/me répond 401 : l'utilisateur n'a pas accès à l'application dans cet environnement, ou le jeton a expiré.

Toutes les causes et solutions sont dans Résoudre les problèmes de connexion.

Voir aussi