Renouveler les clés

English · Type : procédure · Public : administrateur · Contexte : Studio hébergé · Statut : prête · S'applique depuis : 4.2.3

Le Studio Server (Studio d'équipe hébergé) · contrat : expérimental · vérifié par la CI (matrice de support de la 4.4.0, 2026-10-23) : Postgres, S3 et Keycloak en CI ; Chromium et Firefox (job studio-hosted) ; WebKit sous macOS, à la main seulement · vérifications automatiques : jobs studio-hosted, studio-install-smoke ; plan de CI studioHosted ; 3 fichiers de tests · passes humaines : studio-hosted pas faite (#149), studio-collab pas faite (#150), studio-preview pas faite (#166), studio-assets-hosted pas faite (#167), studio-mcp-remote pas faite (#196), studio-oidc-generic pas faite (#197) · limites connues : builds-old-key

Comment remplacer chaque secret d’un Studio hébergé, et ce que chaque changement fait aux personnes connectées : la clé de session, la clé des jobs du worker, le secret client du fournisseur, la clé de déploiement Git et le jeton des métriques.

Ce que vous obtenez

Un nouveau secret en place, l’ancien retiré, et personne de déconnecté sauf si vous le choisissez (une clé de session compromise).

Contexte et versions

Un Studio hébergé sur Clever Cloud, à partir de la 4.2.3 (STUDIO_GIT_KEY et STUDIO_METRICS_TOKEN sont arrivés en 4.2.3).
Vérifié sur : non vérifié sur une installation réelle. Aucun renouvellement n’a été exercé sur le déploiement de référence. Les effets sur les sessions sont lus dans le code ; ceux de la clé de session sont appuyés par le test nommé plus bas.

Prérequis

Configuration faite, les secrets actuels dans ~/secrets/my-game/ (0600).
openssl, et le dépôt du moteur, npm ci fait.

Où lancer les commandes

Sur votre machine, dans le dépôt du moteur où les deux applications sont liées. Un changement de variable s’applique au déploiement ou au redémarrage suivant, et un redémarrage, c’est le chevauchement des Redéploiements : prévoyez sa minute d’écritures lentes. Ne montrez jamais la sortie de clever env : elle affiche les valeurs (Configuration).

Étapes

`STUDIO_SESSION_KEY`

Le cookie de session est un jeton aléatoire stocké par son hash : il ne dépend pas de cette clé. La clé scelle le jeton de rafraîchissement et l’id_token de chaque session (AES-256-GCM). C’est un trousseau, séparé par des virgules : la première clé scelle, n’importe laquelle ouvre.

Créez une nouvelle clé et mettez-la en premier, l’ancienne après :

# sur votre machine, dans le dépôt du moteur
openssl rand -base64 48 > ~/secrets/my-game/session-key.new && chmod 600 ~/secrets/my-game/session-key.new
clever env set --alias my-game-studio -- STUDIO_SESSION_KEY "$(cat ~/secrets/my-game/session-key.new),$(cat ~/secrets/my-game/session-key)"
clever restart --alias my-game-studio

Personne n’est déconnecté. Les nouvelles connexions sont scellées avec la nouvelle clé ; les sessions existantes s’ouvrent toujours avec l’ancienne.

Après la durée absolue des sessions (24 h par défaut, sessions.absoluteHours), chaque session scellée avec l’ancienne clé a pris fin. Retirez-la du trousseau, et gardez le nouveau fichier comme fichier courant :

# sur votre machine, dans le dépôt du moteur
mv ~/secrets/my-game/session-key.new ~/secrets/my-game/session-key
clever env set --alias my-game-studio -- STUDIO_SESSION_KEY "$(cat ~/secrets/my-game/session-key)"
clever restart --alias my-game-studio

Si la clé a fuité, sautez le trousseau : posez la nouvelle clé seule et redémarrez. La vérification suivante de chaque session par le fournisseur (sous 5 min) ne peut plus ouvrir son jeton de rafraîchissement, et la session prend fin : le membre voit « the session can no longer be checked: log in again » (401) et se reconnecte. Les jetons Bearer de la CLI et du MCP ne sont pas scellés par cette clé et ne sont pas touchés.

Garantie · unreadable-session-ends · référencée · exécutée sur aff6caab7514 · portée vérifiée par son auteur (IA), pas relue Une session dont le jeton de rafraîchissement scellé ne s’ouvre plus (sa clé a quitté le trousseau) prend fin à sa vérification suivante, avec un 401, plutôt que de vivre sans vérification jusqu’à sa durée absolue.

`STUDIO_WORKER_KEY` et `WORKER_PUBLIC_KEY`

Le Studio signe chaque job avec la clé privée ; le worker n’accepte que les jobs que sa clé publique vérifie. Le worker ne tient qu’une clé publique à la fois : il y a donc une fenêtre pendant laquelle les jobs sont refusés.

Créez une nouvelle paire dans un nouveau dossier (la commande refuse d’écraser une clé) :

# sur votre machine, dans le dépôt du moteur
mkdir -p ~/secrets/my-game/keys-new && npm run studio-server -- worker-keys --out ~/secrets/my-game/keys-new

Posez les deux variables, puis redémarrez le worker et le studio l’un juste après l’autre :
```
# sur votre machine, dans le dépôt du moteur
clever env set --alias my-game-worker -- WORKER_PUBLIC_KEY "$(cat ~/secrets/my-game/keys-new/studio-worker.pub)"
clever env set --alias my-game-studio -- STUDIO_WORKER_KEY "$(cat ~/secrets/my-game/keys-new/studio-worker.key)"
clever restart --alias my-game-worker
clever restart --alias my-game-studio
```
Entre les deux, le worker refuse les jobs de l’ancien Studio (403) : les écritures qui demandent une vérification sont refusées en 503 (« the edit cannot be judged now: … »), les prévisualisations et la santé échouent et sont retentées. Les sessions ne sont pas touchées.

Limite · builds-old-key Les builds publiés gardent la signature faite avec l’ancienne clé ; leur manifeste nomme cette clé par son identifiant (un hash de la clé publique). Gardez l’ancien studio-worker.pub pour vérifier les builds publiés avant le renouvellement.

`STUDIO_OIDC_CLIENT_SECRET`

Régénérez le secret du client studio chez le fournisseur (dans Keycloak : l’onglet Credentials du client), enregistrez-le dans le fichier 0600, posez-le, et redémarrez le studio aussitôt :
```
# sur votre machine, dans le dépôt du moteur
clever env set --alias my-game-studio -- STUDIO_OIDC_CLIENT_SECRET "$(cat ~/secrets/my-game/oidc-client-secret)"
clever restart --alias my-game-studio
```
Jusqu’au redémarrage, les nouvelles connexions échouent. Le fournisseur répond alors aux vérifications des sessions invalid_client, que le Studio traite comme sa propre erreur de configuration, pas celle de l’utilisateur : une session continue jusqu’à R (15 min) après sa dernière vérification, puis elle est suspendue (503) jusqu’à ce que le secret corresponde de nouveau. Personne n’est déconnecté si le redémarrage arrive à temps.

`STUDIO_GIT_KEY`

Ajoutez une nouvelle clé de déploiement au dépôt du jeu chez votre hébergeur Git, posez-la, redémarrez, puis retirez l’ancienne clé chez l’hébergeur :

# sur votre machine, dans le dépôt du moteur (ssh-keygen écrit la paire ; le .pub va chez l'hébergeur Git)
ssh-keygen -t ed25519 -N '' -C my-game-studio -f ~/secrets/my-game/git-deploy-key-new
clever env set --alias my-game-studio -- STUDIO_GIT_KEY "$(cat ~/secrets/my-game/git-deploy-key-new)"
clever restart --alias my-game-studio

Aucun effet sur les sessions. Un push ou un import pendant la bascule peut échouer, et se relance.

`STUDIO_METRICS_TOKEN`

Créez un nouveau jeton (32 caractères ou plus), posez-le, redémarrez, et donnez-le à votre collecteur. Entre le redémarrage et la mise à jour du collecteur, /metrics répond 401 : attendez-vous à un trou dans les courbes.

Résultat attendu, et comment le vérifier

Clé de session : les membres continuent de travailler après l’étape 1 ; après l’étape 2, une session plus ancienne que le changement du trousseau aurait de toute façon pris fin.
Clé du worker : une écriture qui demande une vérification passe de nouveau, et une prévisualisation se construit ; le worker ne consigne aucun worker-job-refused.
Secret OIDC : une nouvelle connexion marche ; /auth/me répond.
Clé Git : un push depuis le Studio réussit.
Jeton des métriques : la cible du collecteur est de nouveau joignable.

Erreurs fréquentes

Symptôme	Cause	Correction
`a session key is 32 characters or more` au démarrage	Une clé trop courte dans le trousseau	`openssl rand -base64 48`
Tout le monde déconnecté sous 5 min	L’ancienne clé de session retirée d’un coup (sans trousseau)	Attendu pour une clé qui a fuité ; sinon faites d’abord l’étape 1
Écritures en 503 « the edit cannot be judged now: the processing worker refused the job (403…) »	Le worker et le studio ont des clés différentes	Finissez l’étape 4 sur les deux applications
503 « the identity provider cannot be reached: the session is suspended »	Le secret OIDC changé chez le fournisseur, pas encore dans le Studio depuis plus de R	Posez le nouveau secret et redémarrez
`clever env set` lit la clé comme une option	Pas de `--` avant le nom	La forme des commandes

Fichiers ou données modifiés

Les variables des applications ; les fichiers de clés dans ~/secrets/my-game/ ; chez le fournisseur et l’hébergeur Git, le secret du client et les clés de déploiement. Les sessions ne prennent fin que dans le cas d’une clé qui a fuité.

Reprise ou retour arrière

Chaque étape se défait en reposant la valeur précédente et en redémarrant, tant que vous avez gardé son fichier. Une clé de session retirée du trousseau ne peut pas être rendue aux sessions qu’elle scellait : elles ont pris fin.

Références

Le trousseau : studio-server/src/server/auth/store.ts (Sealer) ; les vérifications : studio-server/src/server/auth/gate.ts ; les erreurs de rafraîchissement : studio-server/src/server/auth/oidc.ts ; les clés des jobs : studio-server/src/worker/job.ts ; la signature des builds : studio-server/src/server/builds.ts.
STUDIO_SESSION_KEY, STUDIO_WORKER_KEY, STUDIO_GIT_KEY, STUDIO_METRICS_TOKEN.
Le test derrière la garantie : tests/studio-auth.test.ts.

Modifier la source de cette page · Signaler une erreur