WakaStart
Authentification

Authentification — Concepts & Flow

Vue d'ensemble du flow OAuth2 PKCE Wakastart : concepts clés, diagramme complet et prérequis Keycloak.

Version v1.04 min de lecture

Authentification — Concepts & Flow

Depuis IAM-S0 / IAM-C4 (mai 2026) — Le realm Keycloak n'est plus construit côté frontend. Discovery expose un endpoint public POST /discover/start-login qui résout le realm + le client_id à partir du host et retourne une URL Keycloak prête à suivre. Aucune Wakapp ne détient INTERNAL_API_SECRET.

Pourquoi cette étape

L'authentification est le flux le plus critique de votre intégration. Un flux mal implémenté expose à des vulnérabilités (code interception, CSRF, token leakage). Le PKCE (Proof Key for Code Exchange) est obligatoire et garantit qu'un code OIDC volé en transit est inutilisable sans le code_verifier connu uniquement du client légitime.

Le flow Wakastart ajoute deux étapes propres à la plateforme : le start-login (Discovery résout le realm) et l'enrich (le BFF enrichit le JWT Keycloak avec les rôles métier).

Concepts clés

  • code_verifier : chaîne aléatoire 43-128 chars, générée côté client, stockée en sessionStorage.
  • code_challenge : BASE64URL(SHA256(code_verifier)), envoyé à Keycloak.
  • access_token : JWT RS256 émis par Keycloak, durée de vie courte (5-15 min).
  • refresh_token : token longue durée pour obtenir de nouveaux access_token.
  • wakaToken : JWT HS256 émis par ws-serv-token, contient les droits métier. Obligatoire pour appeler les services downstream.
  • enrichment : étape propriétaire qui transforme le JWT Keycloak basique en wakaToken enrichi.

Flow complet en 10 étapes

Chargement du diagramme…

Pré-requis Keycloak — Client OIDC

Pour que le flow fonctionne, le client OIDC doit être configuré ainsi :

ParamètreValeurRaison
Client IDValeur de apps.client_id en DB (auto-généré du WID)Discovery résout ce client_id
Client authenticationOFF (public client)PKCE sans secret — obligatoire
AuthorizationOFFNon nécessaire
Standard flowONFlow OAuth2 PKCE
Direct access grantsOFF (recommandé)Éviter le Resource Owner Password Credentials
Implicit flowOFFDéprécié, non sécurisé
PKCE MethodS256Obligatoire
Valid redirect URIshttps://app.<tenant>.<platform>/*Exact match Keycloak
Web originshttps://app.<tenant>.<platform>CORS pre-flight

Client authentication: ON cause Invalid client or Invalid client credentials au token exchange — Keycloak attend un client_secret que PKCE public ne fournit pas. C'est la première chose à vérifier en cas de 401 au callback.

Organizations Keycloak (IAM-C4 — obligatoire)

ws-serv-token rejette tout token Keycloak sans le claim organization. Trois conditions doivent être remplies :

1. Realm — feature Organizations activée

Console Keycloak → realm → Realm settings → General → "Organizations enabled"

Cela crée automatiquement un client scope organization au niveau realm.

2. Client OIDC — scope organization attaché comme default

Console Keycloak → realm → Clients → {client_id} → Client scopes → ajouter "organization" en Default

Automatisé par npx prisma db seed (ws-serv-config).

3. User — membre d'une organisation Keycloak Pour chaque Customer en DB, une organisation Keycloak existe (alias = customer.wid). Les users actifs doivent y être membres. Automatisé par npx ts-node prisma/backfill-keycloak-orgs.ts (idempotent).

Sans ces 3 conditions : enrichment retourne 401 et l'utilisateur voit une erreur "Token enrichi manquant ou invalide".

Gestion d'erreurs au callback

CasSymptômeSolution
redirect_uri mismatch400 Invalid redirect_uri KeycloakVérifier exact match URI dans la console Keycloak
client_id incorrect401 Invalid clientExtraire client_id depuis la keycloakUrl, ne pas hardcoder
code_verifier incorrect400 invalid_grantVérifier cohérence verifier/challenge (ne pas re-encoder)
organization absent401 Token enrichi manquantActiver Organizations + scope sur le client (voir ci-dessus)
Enrich échouewakastart_token absent des cookiesLogger la réponse HTTP de /api/auth/enrich

Aller plus loin