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.
- Durée
- 20 min
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 :
- demande à Discovery l'adresse de connexion, à partir du nom d'hôte de votre front ;
- redirige l'utilisateur vers cette adresse, protégée par PKCE et
state; - reçoit le code d'autorisation sur
/api/auth/callbacket l'échange contre des jetons auprès de Keycloak ; - appelle
GET https://api.wakastart.app/api/meet affiche l'identité, l'organisation et les droits de l'utilisateur ; - le déconnecte.
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 retourhttps://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 :
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 :
{
"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 :
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 :
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 :
PUBLIC_URL=https://mon-app.exemple.fr npx tsx server.tsSortie attendue :
Serveur prêt sur le port 3000 pour https://mon-app.exemple.frOuvrez 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 :
{
"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
hostest obligatoire et vaut le nom d'hôte complet du front, en minuscules, sanshttps://ni chemin. Il désigne à la fois l'application et l'environnement, donc les fiches utilisateurs consultées. Chaque environnement a son proprePUBLIC_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_URLde 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 dehost, ou utilisezGET /discover/emailavecdomain, 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.