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

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](/v1.0/glossaire#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.

```mermaid
sequenceDiagram
  autonumber
  actor U as Utilisateur
  participant S as Votre serveur
  participant D as Discovery
  participant K as Keycloak de l'environnement
  participant A as API publique
  U->>S: GET /login
  S->>D: POST /discover/start-login { host, redirectUri, state, codeChallenge }
  D-->>S: { keycloakUrl }
  S-->>U: redirection vers keycloakUrl
  U->>K: identifiant et mot de passe (ou SSO)
  K-->>U: redirection vers /api/auth/callback?code=…&state=…
  U->>S: GET /api/auth/callback
  S->>K: POST …/token { code, code_verifier }
  K-->>S: access_token, refresh_token
  S->>A: GET /api/me (Bearer access_token)
  A-->>S: identité, organisation, profil, droits
  S-->>U: page d'accueil connectée
```

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](/v1.0/demarrer/deployer-votre-premier-service)) ou placez-le derrière votre propre proxy HTTPS. Keycloak refuse toute autre adresse de retour.
:::

::::steps
### 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` :

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

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

Sortie attendue :

```text
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.
::::

:::tip[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](/v1.0/concepts/discovery).
- **Le jeton doit avoir été émis pour votre application.** L'API publique refuse un jeton obtenu pour une autre application.

## Étapes suivantes

::::cards{cols=3}
:::card{title="Discovery" href="/v1.0/concepts/discovery" icon="Search"}
Les trois façons de résoudre le realm, et ce qu'il ne faut pas faire.
:::
:::card{title="Jeton enrichi et /me" href="/v1.0/concepts/jeton-enrichi-et-me" icon="BadgeCheck"}
Ce que contient chaque jeton, et quand appeler `/api/me`.
:::
:::card{title="Authentification" href="/v1.0/authentification" icon="LogIn"}
Rafraîchir les jetons, brancher un SSO, passer en production.
:::
::::
