Skip to content

doc: documenter la bascule complète de l'API Console vers NestJS #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shikanime wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: documenter la bascule complète de l'API Console vers NestJS #131

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/platform/iam.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Cette page présente l’IAM de la Console (Identity & Access Management) : auth

L’IAM repose sur Keycloak pour l’identité (OIDC), une authentification backend via session ou jeton API, et une autorisation calculée côté serveur avec des bitmasks BigInt.

L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.
L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.

@StephaneTrebel StephaneTrebel Oct 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ suggestion (lisibilité): Expliquer la connexion avant les détails du protocole

« Le client attache un jeton » et « le backend résout l’identité » supposent de connaître le fonctionnement d’une application web. Proposition :

Lorsqu’un utilisateur se connecte, Keycloak lui fournit un jeton d’accès. L’application web transmet ce jeton à l’API dans l’en-tête Authorization: Bearer <jeton>. Le serveur vérifie le jeton et en extrait l’identité de l’utilisateur. Pour les scripts et les outils automatisés, un jeton d’API peut être transmis dans l’en-tête x-dso-token.

Les noms techniques des champs (sub, given_name…) peuvent rester dans une seconde phrase destinée aux intégrateurs, plutôt que d’interrompre l’explication de base.

@StephaneTrebel StephaneTrebel Oct 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit (cohérence): Aligner aussi la phrase de synthèse sur l’authentification décrite ici

Le nouveau texte remplace la session par un jeton Bearer :

-L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.
+L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.

Mais la ligne juste au-dessus annonce toujours une « authentification backend via session ou jeton API ». Harmoniser cette synthèse avec le nouveau paragraphe éviterait de faire croire à deux mécanismes navigateur concurrents.


L’API de la Console est désormais servie intégralement par le backend NestJS : les anciens endpoints V1 `/api/v1/environments` et `/api/v1/repositories` ne sont pas repris, utilisez leurs équivalents V2 sous `/api/v2/projects/:projectId/`. Le Swagger historique `/swagger-ui` n’est plus servi (404) ; la documentation d’API maintenue est disponible à `/swagger-ui-server-nestjs`. À la création d’un jeton d’API, une date d’expiration laissée vide est acceptée et équivaut à l’absence d’expiration.

@StephaneTrebel StephaneTrebel Oct 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ suggestion (structure): Séparer les trois informations et donner les chemins de remplacement complets

Ce paragraphe mélange migration des routes, accès à la documentation et expiration des jetons. Un lecteur cherchant une seule de ces informations doit tout déchiffrer ; « sous /api/v2/projects/:projectId/ » ne donne pas encore les routes à appeler.

Je proposerais un petit bloc « Si vous utilisez l’API », avec :

  • un tableau anciennes routes → routes V2 complètes (…/:projectId/environments et …/:projectId/repositories), en précisant que :projectId est à remplacer par l’identifiant du projet ;
  • « Consultez la documentation interactive de l’API à l’adresse /swagger-ui-server-nestjs. L’ancienne adresse /swagger-ui renvoie désormais une erreur 404. » ;
  • une phrase séparée sur les jetons : « Si vous laissez la date d’expiration vide, le jeton reste valable sans limite de durée. »

Cela évite aussi les termes non expliqués « endpoints » et « Swagger » comme seuls points de repère.


L’autorisation combine des permissions globales et projet par cumul : les droits attribués à l’utilisateur sont calculés à partir de l’ensemble de ses rôles.

Expand Down
Loading