Adapter votre application aux fiches par environnement
Le WID d'un utilisateur présent sur plusieurs environnements change. Retrouvez vos utilisateurs par sub ou e-mail, et retirez les paramètres d'environnement.
- Accès requis
- Développeur de l'application
- Durée
- 30 min
Chaque environnement de votre application (dev, staging, prod) a désormais son propre référentiel d'utilisateurs. Une personne présente sur plusieurs environnements a une fiche, donc un WID, par environnement. Ce guide vous aide à adapter votre application avant la bascule : retrouver vos utilisateurs sans dépendre d'un WID, et cesser d'envoyer un environnement à l'API.
Ce qui change
Jusqu'ici, une personne n'avait qu'une fiche, partagée entre les environnements de l'application. Désormais, une adresse présente en dev, en staging et en prod correspond à trois fiches indépendantes : désactiver, renommer ou supprimer l'une ne touche pas les autres. Le modèle est décrit dans Comptes et environnements.
À la bascule, la fiche unique d'une personne présente sur plusieurs environnements est éclatée :
| Fiche | id et wid |
|---|---|
Celle de l'environnement le plus haut réellement déployé pour l'application : prod, sinon staging, sinon dev | Conserve l'ancien id et l'ancien WID |
| Chacune des autres | Reçoit un nouvel id et un nouveau WID |
Par exemple, une personne présente en prod et en dev garde son WID en prod et reçoit un nouveau WID en dev. Si l'application n'est déployée qu'en staging et en dev, c'est la fiche de staging qui garde l'ancien WID.
L'ancien WID n'est ni redirigé ni traduit : présenté depuis un autre environnement que celui de la fiche qui l'a gardé, il ne désigne plus aucune fiche et l'API répond 404. Une personne qui n'existait que dans un environnement ne voit aucun changement.
Ce qui ne change pas
| Donnée | Après la bascule |
|---|---|
sub du jeton Keycloak de la personne dans un environnement | Inchangé |
| Adresse e-mail | Inchangée ; elle n'est plus unique que par client et par environnement |
| Profils attribués et droits dans cet environnement | Inchangés |
| WID des profils, des clients, des réseaux et des applications | Inchangés |
| WID de la fiche de l'environnement le plus haut déployé | Inchangé |
keycloakId, renvoyé par les endpoints de contrôle de jeton (/api/token/*), désigne désormais le compte Keycloak de l'environnement de la session ; il valait auparavant le compte de production, même en session dev. Il est donc égal au sub du jeton dans tous les environnements.
Avant de commencer
- Repérez dans votre base les endroits où vous stockez le WID ou l'
idd'un utilisateur Wakastart pour le retrouver plus tard. Ce sont eux qui cessent de fonctionner dans un environnement où la personne reçoit un nouveau WID. - Repérez les appels à l'API publique qui envoient
env,envTypeouenvs.
Choisir une méthode de rattachement
Choisissez l'une des trois méthodes et déployez-la dans chaque environnement avant la bascule.
Rattacher vos utilisateurs au sub (recommandé)
Le sub du jeton identifie le compte Keycloak de la personne dans l'environnement de la session, et il ne change pas. Utilisez-le comme clé de rattachement :
import { decodeJwt } from "jose";
// À chaque connexion : retrouver l'utilisateur local par son sub, jamais par son WID
const claims = decodeJwt(enrichedToken);
const localUser = await db.user.upsert({
where: { keycloakSub: claims.sub as string },
update: { email: claims.email as string },
create: { keycloakSub: claims.sub as string, email: claims.email as string },
});Résultat : vos utilisateurs locaux sont retrouvés quel que soit le WID de leur fiche.
Ou retrouver l'utilisateur par e-mail
Depuis votre serveur, la recherche par e-mail renvoie la fiche de l'environnement de l'appelant :
/api/config/users/searchcurl "https://api.wakastart.app/api/config/users/search?email=alice@exemple.fr" \
-H "x-api-key: sk_test_exemple"const response = await fetch(
`https://api.wakastart.app/api/config/users/search?email=${encodeURIComponent("alice@exemple.fr")}`,
{ headers: { "x-api-key": process.env.WAKASTART_API_KEY! } },
);
const { items } = await response.json();Réponse attendue :
{ "items": [{ "wid": "Ab12Cd", "email": "alice@exemple.fr", "envType": "dev" }] }La recherche porte sur l'adresse exacte, sans tenir compte de la casse, dans votre périmètre et dans l'environnement de la clé ou du jeton. N'envoyez que email.
Ou rafraîchir le WID à chaque connexion
Si votre modèle impose de stocker le WID, relisez-le dans /api/me à chaque connexion et mettez à jour votre copie, en retrouvant votre utilisateur local par sub ou par e-mail :
const me = await fetch("https://api.wakastart.app/api/me", {
headers: { Authorization: `Bearer ${accessToken}`, "x-enriched-token": enrichedToken },
}).then((r) => r.json());
if (localUser.wakastartWid !== me.wid) {
await db.user.update({ where: { id: localUser.id }, data: { wakastartWid: me.wid } });
}Résultat : le WID stocké est toujours celui de la fiche de l'environnement courant.
Retirer les paramètres d'environnement
L'environnement est désormais déduit de l'appelant : claim wenv du jeton, environnement de la clé API, ou hôte appelé pour Discovery. Vérifiez chacun de ces points dans votre code :
- Retirez
env,envTypeetenvsde vos appels à l'API publique : ils sont refusés en400avec le messageEnvironment is deduced from the caller and cannot be provided. Sont concernés la création d'un utilisateur (envs), la liste des utilisateurs (envType), les invitations (envType) et les droits d'un profil (env,envType). - Utilisez une clé API par environnement : les droits d'une clé se lisent dans la matrice profils × droits de l'environnement de la clé. Une clé de dev ou de staging peut gagner ou perdre des droits par rapport à avant, où la matrice de production s'appliquait. Une clé sans environnement est refusée (
403). - Un jeton dont l'environnement ne peut pas être déduit est refusé (
401) : il n'y a plus de repli sur la production. - Désignez un profil par son WID, sur les routes de profils comme dans les invitations (
profileWid). - Envoyez à Discovery le hostname de la page dans chaque build :
hostsurstart-login,domainsur la recherche par e-mail. Un build de dev qui envoie le hostname de production s'authentifie sur les fiches de production. Voir Discovery.
Vérifier le résultat
- Dans chaque environnement, un utilisateur qui existe aussi ailleurs se connecte et retrouve ses données dans votre application.
- Aucun de vos appels ne reçoit de
400Environment is deduced from the caller and cannot be provided. GET /api/merenvoie, dans chaque environnement, lewidde la fiche de cet environnement, et votre application retrouve le même utilisateur local.