Skip to content

Connecter vos utilisateurs

Intégrer la connexion Wakastart dans une wakapp en TypeScript, de Discovery à la déconnexion, avec PKCE et l'appel à /api/me.

QuickstartDeveloper
Duration
20 min

This page has not been translated yet and is shown in French.

Ce démarrage rapide branche la connexion Wakastart dans votre application, de bout en bout. Vous écrivez un petit serveur TypeScript, sans dépendance, qui confie l'authentification à Keycloak et lit ensuite le profil de l'utilisateur dans l'API publique.

Ce que vous allez construire

Un serveur qui :

  1. demande à Discovery l'adresse de connexion, à partir du nom d'hôte de votre front ;
  2. redirige l'utilisateur vers cette adresse, protégée par PKCE et state ;
  3. reçoit le code d'autorisation sur /api/auth/callback et l'échange contre des jetons auprès de Keycloak ;
  4. appelle GET https://api.wakastart.app/api/me et affiche l'identité, l'organisation et les droits de l'utilisateur ;
  5. le déconnecte.
Loading diagram…

Votre code ne contient ni URL Keycloak, ni realm, ni identifiant client : tout est lu dans la réponse de Discovery.

Avant de commencer

  • Une application Wakastart et un environnement. Votre application est créée par Wakastart ; contactez-nous pour en ouvrir une.
  • Le nom d'hôte public de votre front, par exemple mon-app.exemple.fr, déclaré dans les hôtes IAM de cet environnement (console : environnement > onglet URLs & IAM). Wakastart y associe l'adresse de retour https://mon-app.exemple.fr/api/auth/callback, seule adresse acceptée par Keycloak. Si l'hôte manque, demandez-le à votre administrateur réseau ou à l'équipe Wakastart.
  • Un compte de test qui a accès à l'application dans cet environnement, avec un profil attribué.
  • Node.js 20 ou plus récent.

Important

Le serveur doit répondre sur l'URL publique du front, en HTTPS : déployez-le comme service Frontend de votre application (voir Déployer votre premier service) ou placez-le derrière votre propre proxy HTTPS. Keycloak refuse toute autre adresse de retour.

Vérifier que Discovery reconnaît votre front

Dans un terminal, envoyez le nom d'hôte de votre front à Discovery :

Bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "mon-app.exemple.fr",
    "redirectUri": "https://mon-app.exemple.fr/api/auth/callback"
  }'

Réponse attendue :

JSON
{
  "keycloakUrl": "https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/auth?client_id=EXAPP1&response_type=code&scope=openid+profile+email+organization&redirect_uri=https%3A%2F%2Fmon-app.exemple.fr%2Fapi%2Fauth%2Fcallback"
}

L'instance (auth.wakastart.app en production, auth-staging.wakastart.app en staging, auth-dev.wakastart.app en développement) dépend de l'environnement auquel l'hôte est rattaché. Si vous obtenez 404 avec "message": "not_found", le nom d'hôte n'est déclaré dans aucun hôte IAM : vérifiez l'orthographe, sans https:// ni chemin.

Créer le projet

Créez un dossier et installez tsx, qui exécute TypeScript directement :

Bash
mkdir wakapp-connexion && cd wakapp-connexion
npm init -y
npm install --save-dev tsx @types/node

Écrire le serveur

Créez le fichier server.ts :

server.tsTypeScript
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { createHash, randomBytes } from "node:crypto";

// URL publique de votre front, telle qu'elle est déclarée dans les hôtes IAM.
const PUBLIC_URL = process.env.PUBLIC_URL ?? "https://mon-app.exemple.fr";
const PORT = Number(process.env.PORT ?? 3000);

const DISCOVERY_URL = "https://discovery.wakastart.app";
const API_URL = "https://api.wakastart.app/api";
const REDIRECT_URI = `${PUBLIC_URL}/api/auth/callback`;
const SECURE_COOKIE = PUBLIC_URL.startsWith("https://");

interface Session {
  state?: string;
  codeVerifier?: string;
  issuer?: string; // https://<instance>/realms/<realm>, lu dans la keycloakUrl
  clientId?: string; // client_id de votre application, lu dans la keycloakUrl
  accessToken?: string;
  refreshToken?: string;
}

// Sessions en mémoire : suffisant pour ce démarrage rapide, pas pour la production.
const sessions = new Map<string, Session>();

const base64url = (buf: Buffer) => buf.toString("base64url");

function getSession(req: IncomingMessage, res: ServerResponse): Session {
  const sid = /(?:^|;\s*)sid=([^;]+)/.exec(req.headers.cookie ?? "")?.[1];
  if (sid && sessions.has(sid)) return sessions.get(sid)!;
  const newSid = base64url(randomBytes(24));
  const session: Session = {};
  sessions.set(newSid, session);
  res.setHeader(
    "Set-Cookie",
    `sid=${newSid}; HttpOnly; SameSite=Lax; Path=/${SECURE_COOKIE ? "; Secure" : ""}`,
  );
  return session;
}

function redirect(res: ServerResponse, location: string) {
  res.writeHead(302, { Location: location }).end();
}

function html(res: ServerResponse, status: number, body: string) {
  res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" }).end(body);
}

const escape = (s: string) =>
  s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);

// 1. Demander l'URL de connexion à Discovery, puis rediriger l'utilisateur.
async function login(session: Session, res: ServerResponse) {
  const codeVerifier = base64url(randomBytes(32));
  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
  const state = base64url(randomBytes(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 complet du front
      redirectUri: REDIRECT_URI,
      state,
      codeChallenge,
      codeChallengeMethod: "S256",
    }),
  });
  if (!response.ok) {
    return html(res, 502, `<p>Discovery a répondu ${response.status}.</p>`);
  }
  const { keycloakUrl } = (await response.json()) as { keycloakUrl: string };

  // L'instance, le realm et le client_id se lisent dans l'URL renvoyée.
  const authUrl = new URL(keycloakUrl);
  session.issuer = authUrl.origin + authUrl.pathname.replace(/\/protocol\/openid-connect\/auth$/, "");
  session.clientId = authUrl.searchParams.get("client_id") ?? undefined;
  session.codeVerifier = codeVerifier;
  session.state = state;

  redirect(res, keycloakUrl);
}

// 2. Recevoir le code et l'échanger contre des jetons auprès de Keycloak.
async function callback(session: Session, url: URL, res: ServerResponse) {
  const code = url.searchParams.get("code");
  if (!code || !session.state || url.searchParams.get("state") !== session.state) {
    return html(res, 400, "<p>Retour de connexion invalide.</p>");
  }

  const response = await fetch(`${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: session.clientId!,
      code_verifier: session.codeVerifier!,
    }),
  });
  if (!response.ok) {
    return html(res, 401, `<p>Échange du code refusé (${response.status}).</p>`);
  }
  const tokens = (await response.json()) as { access_token: string; refresh_token: string };

  session.accessToken = tokens.access_token;
  session.refreshToken = tokens.refresh_token;
  delete session.state;
  delete session.codeVerifier;

  redirect(res, "/");
}

// 3. Lire l'utilisateur connecté dans l'API publique.
async function home(session: Session, res: ServerResponse) {
  if (!session.accessToken) {
    return html(res, 200, '<p><a href="/login">Se connecter</a></p>');
  }
  const response = await fetch(`${API_URL}/me`, {
    headers: { Authorization: `Bearer ${session.accessToken}` },
  });
  if (!response.ok) {
    // 401 : jeton expiré, ou utilisateur sans accès à l'application dans cet environnement.
    if (response.status === 401) delete session.accessToken;
    return html(
      res,
      response.status,
      `<p>L'API a répondu ${response.status}. <a href="/login">Se reconnecter</a></p>
       <pre>${escape(await response.text())}</pre>`,
    );
  }
  const me = await response.json();
  html(
    res,
    200,
    `<p>Connecté. <a href="/logout">Se déconnecter</a></p>
     <pre>${escape(JSON.stringify(me, null, 2))}</pre>`,
  );
}

// 4. Fermer la session Keycloak, puis la session locale.
async function logout(req: IncomingMessage, session: Session, res: ServerResponse) {
  if (session.refreshToken) {
    await fetch(`${session.issuer}/protocol/openid-connect/logout`, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        client_id: session.clientId!,
        refresh_token: session.refreshToken,
      }),
    });
  }
  const sid = /(?:^|;\s*)sid=([^;]+)/.exec(req.headers.cookie ?? "")?.[1];
  if (sid) sessions.delete(sid);
  redirect(res, "/");
}

createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", PUBLIC_URL);
  const session = getSession(req, res);
  try {
    if (url.pathname === "/login") return await login(session, res);
    if (url.pathname === "/api/auth/callback") return await callback(session, url, res);
    if (url.pathname === "/logout") return await logout(req, session, res);
    if (url.pathname === "/") return await home(session, res);
    html(res, 404, "<p>Page introuvable.</p>");
  } catch (err) {
    console.error(err);
    html(res, 500, "<p>Erreur inattendue.</p>");
  }
}).listen(PORT, () => console.log(`Serveur prêt sur le port ${PORT} pour ${PUBLIC_URL}`));

Le serveur écoute en HTTP sur le port 3000 : le HTTPS est assuré devant lui, par Wakastart ou par votre proxy.

Lancer le serveur et se connecter

Démarrez le serveur avec l'URL publique de votre front :

Bash
PUBLIC_URL=https://mon-app.exemple.fr npx tsx server.ts

Sortie attendue :

Texte
Serveur prêt sur le port 3000 pour https://mon-app.exemple.fr

Ouvrez https://mon-app.exemple.fr/login dans un navigateur. La page de connexion de votre application s'affiche, aux couleurs de votre réseau ou de votre client. Connectez-vous avec le compte de test.

Vérifier que ça marche

Après la connexion, la page d'accueil affiche Connecté et la réponse de GET /api/me, par exemple :

JSON
{
  "wid": "EXUSR1",
  "email": "claire.martin@exemple.fr",
  "firstName": "Claire",
  "lastName": "Martin",
  "isActive": true,
  "adminLevel": "NONE",
  "hdsRoles": [],
  "customer": { "wid": "EXCLI1", "name": "Clinique Exemple" },
  "branding": {
    "logoLightUrl": "https://cdn.exemple.fr/logo-clair.png",
    "primaryColor": "#0f766e"
  },
  "teams": [],
  "profile": {
    "wid": "EXPRF1",
    "name": "Soignant",
    "description": "Consultation et mise à jour des dossiers",
    "rights": [
      { "code": "dossiers.read", "name": "Lire les dossiers", "category": "Dossiers" },
      { "code": "dossiers.update", "name": "Modifier les dossiers", "category": "Dossiers" }
    ]
  },
  "lastLoginAt": "2026-10-23T09:12:44.000Z",
  "createdAt": "2026-09-02T14:05:10.000Z",
  "partner": { "wid": "EXPAR1", "name": "Éditeur Exemple" },
  "network": { "wid": "EXNET1", "name": "Réseau Exemple" }
}

profile.rights contient les droits du profil de l'utilisateur dans l'environnement de connexion : c'est cette liste que votre code consulte avant d'autoriser une action. Cliquez ensuite sur Se déconnecter : la session Keycloak est fermée et le lien Se connecter réapparaît.

Tester depuis votre poste

Dans un environnement de développement, un hôte local de la forme <nom court de l'app>.localhost:3000 peut être déclaré dans les hôtes IAM. Lancez alors le serveur avec PUBLIC_URL=http://<nom court>.localhost:3000 : Keycloak accepte http pour ces adresses locales.

Ce qu'il faut retenir

  • host est obligatoire et vaut le nom d'hôte complet du front, en minuscules, sans https:// ni chemin. Il désigne à la fois l'application et l'environnement, donc les fiches utilisateurs consultées. Chaque environnement a son propre PUBLIC_URL : un build de dev qui enverrait le nom d'hôte de production connecterait ses utilisateurs sur les fiches de production.
  • L'URL Keycloak ne s'écrit jamais en dur. Elle vient de la réponse de Discovery, ou de la variable KEYCLOAK_URL de votre application, posée par environnement.
  • N'envoyez pas d'appId à POST /discover/start-login : le nom d'hôte suffit et garantit le bon environnement. Si plusieurs clients partagent votre nom d'hôte, ajoutez l'e-mail saisi en plus de host, ou utilisez GET /discover/email avec domain, comme décrit dans Discovery.
  • Le jeton doit avoir été émis pour votre application. L'API publique refuse un jeton obtenu pour une autre application.

Étapes suivantes