ADR 0038 – Client officiel d'administration de Keycloak

Statut : Décidée. Date : 01/10/2026. Applique la page « Keycloak multi-clients » (§6.2) et l’EC-042.

Contexte

Les administrateurs clients n’ouvrent jamais la console Keycloak : l’API crée les comptes, les désactive, révoque les sessions et gère les organisations avec deux comptes de service (biotrace-api pour les utilisateurs et les groupes, biotrace-api-organisations pour les organisations, EC-042). Ces appels touchent tout le royaume : le code qui les fait doit être borné et remplaçable.

Décision

@keycloak/keycloak-admin-client (licence Apache 2.0), épinglé en ~26.0.x comme le serveur Keycloak 26.0.5. Il n’est importé que dans apps/api/src/identite/keycloak/, derrière deux interfaces (AdministrationKeycloak, OrganisationsKeycloak). Une règle de lint interdit tout autre import du client ou de l’adaptateur (KC-18). Chaque compte de service a sa propre session client_credentials, renouvelée avant l’expiration du jeton.

Alternatives écartées

• fetch natif : aucune dépendance, mais les routes d’administration (organisations, consentements, groupes) et leurs formats seraient à réécrire et à suivre à chaque version de Keycloak.
• Un seul compte de service avec manage-realm : écarté par l’EC-042, le droit modifie tout le royaume.

Conséquences

Une dépendance d’exécution, ESM pur, chargée par l’API CommonJS grâce au require(esm) de Node 22.12 (vérifié par le build et les tests). Le client doit suivre la version de Keycloak : on change les deux ensemble, comme keycloak-config-cli (ADR 0034). L’adaptateur est testé contre un vrai Keycloak (apps/api/test/identite/keycloak-reel.test.ts), les services contre un faux en mémoire.

Stratégie de sortie

Les services ne connaissent que les deux ports. Remplacer le client officiel par des appels fetch ne change que le dossier identite/keycloak/, sans toucher aux services, aux routes ni aux tests des services.