add iam architecture documentation

docs/.vitepress/sidebar.json

@@ -45,6 +45,10 @@
         "text": "Compatibilité",
         "link": "/platform/compatibility"
       },
+      {
+        "text": "Architecture IAM",
+        "link": "/platform/iam"
+      },
       {
         "text": "Matrice de compétences",
         "link": "/platform/skills-matrix"
@@ -244,6 +248,10 @@
         "text": "Utilisateurs",
         "link": "/administration/utilisateurs"
       },
+      {
+        "text": "Rôles",
+        "link": "/administration/roles"
+      },
       {
         "text": "Organisations",
         "link": "/administration/organisations"

docs/administration/roles.md

@@ -0,0 +1,80 @@
+# Rôles plateforme
+
+Les rôles plateforme pilotent les permissions globales de la Console (scope Console). Ils sont distincts des rôles projet, qui ne s’appliquent qu’à un projet.
+
+Si un utilisateur est associé à plusieurs rôles plateforme, ses permissions sont cumulées : il obtient l’ensemble des permissions de tous ses rôles.
+
+Certains rôles plateforme sont préconfigurés (rôles “système”) et sont en lecture seule : leurs permissions, leur type et leur groupe OIDC ne sont pas modifiables depuis l’interface. La gestion des membres reste possible.
+
+Pour les identifier, vérifier que les champs du rôle sont non modifiables (grisés) dans l’onglet `Général`.
+
+## Accéder à la gestion des rôles
+
+Chemin : `Administration` → `Rôles`.
+
+![Liste des rôles plateforme](/img/iam/admin-roles-list.png)
+
+## Paramétrer un rôle
+
+L’onglet `Général` permet de :
+
+- nommer le rôle ;
+- choisir ses permissions (globales) ;
+- définir le type ;
+- associer le groupe OIDC.
+
+![Paramétrage d’un rôle plateforme](/img/iam/admin-role-general.png)
+
+## Gérer les membres d’un rôle
+
+L’onglet `Membres` permet d’ajouter ou retirer des utilisateurs.
+
+![Membres d’un rôle plateforme](/img/iam/admin-role-members.png)
+
+## Effet sur les services intégrés (exemple GitLab)
+
+La Console est la source de vérité des rôles et permissions. Selon les intégrations actives et le niveau de synchronisation, ces droits peuvent être projetés vers des services externes.
+
+À ce jour, GitLab est le service intégré pour ce contrôle.
+
+Vérifier les points suivants :
+
+- l’intégration du service concerné est active ;
+- le mapping des groupes/rôles est configuré pour ce service ;
+- la synchronisation est terminée.
+
+### Correspondance Console → GitLab (par défaut)
+
+La correspondance ci-dessous reflète la configuration par défaut. Elle peut être adaptée via la configuration du plugin GitLab.
+
+Rôles plateforme (scope Console) :
+
+| Rôle Console (groupe OIDC) | Droits GitLab |
+| --- | --- |
+| `/console/admin` | Administrateur GitLab |
+| `/console/readonly` | Auditeur GitLab |
+
+Rôles projet (scope projet) :
+
+| Rôle Console (groupe OIDC) | Droits GitLab sur le groupe du projet |
+| --- | --- |
+| `/<projectSlug>/console/admin` | Maintainer |
+| `/<projectSlug>/console/devops` | Developer |
+| `/<projectSlug>/console/developer` | Developer |
+| `/<projectSlug>/console/readonly` | Reporter |
+| Propriétaire du projet (Console) | Owner |
+
+Paramètres de configuration utiles (plugin GitLab) :
+
+| Clé | Rôle |
+| --- | --- |
+| `adminGroupPath` | Groupe OIDC donnant les droits d’administrateur GitLab |
+| `auditorGroupPath` | Groupe OIDC donnant les droits d’auditeur GitLab |
+| `projectMaintainerGroupPathSuffix` | Suffixe OIDC donnant l’accès Maintainer |
+| `projectDeveloperGroupPathSuffix` | Suffixe OIDC donnant l’accès Developer |
+| `projectReporterGroupPathSuffix` | Suffixe OIDC donnant l’accès Reporter |
+
+## Voir aussi
+
+- [Gestion des rôles (projet)](/guide/roles)
+- [Utilisateurs](/administration/utilisateurs)

docs/administration/utilisateurs.md

@@ -1,8 +1,9 @@
 # Utilisateurs
 
-Dans le menu Administration > Utilisateurs il est possible de retrouver tous les utilisateurs inscrits sur la plateforme, ainsi que leur statut (utilisateur simple ou administrateur).
+Dans le menu `Administration` → `Utilisateurs`, il est possible de retrouver tous les utilisateurs inscrits sur la plateforme, ainsi que des informations d’administration associées.
 
-> La création et la suppresion des utilisateurs est à faire directement dans keycloak.
+> La création et la suppression des utilisateurs se fait directement dans Keycloak.
+> Après création ou modification d’un utilisateur, un délai de synchronisation peut être nécessaire avant de voir les changements dans la Console.
 
 ## Recherche
 
@@ -18,3 +19,11 @@ Une fonction de recherche est disponible sur les champs suivants:
 ## Devenir administrateur
 
 En cochant la case **Administrateur**, la personne choisie devient administrateur de la console DSO.
+
+Selon la configuration, les permissions globales peuvent aussi être gérées via les rôles plateforme (recommandé).
+
+Quand les rôles plateforme sont activés, ils constituent le mode principal de gestion des droits globaux (plus fin et plus traçable). La case **Administrateur** peut rester disponible selon le paramétrage, mais il est préférable d’utiliser les rôles plateforme pour l’attribution des droits.
+
+La montée en privilège (attribution de droits administrateur) doit suivre votre processus de validation interne.
+
+Voir : [Rôles plateforme](/administration/roles).

docs/guide/roles.md

@@ -1,33 +1,44 @@
 # Gestion des rôles
 
-Les rôles permettent d'augmenter ou diminuer les droits de chaque membre de votre équipe.
+Cette page explique la gestion des rôles au niveau projet.
 
-Si un membre de l'équipe est associé à plusieurs rôles, il prendra les permissions de tous les rôles associés.
+Pour les rôles plateforme (scope Console), voir : [Rôles plateforme](/administration/roles).
 
-Cliquez sur l'onglet **roles**
-![menu-projet-depot](/img/guide/roles/onglets-projet-v9-roles.png)
+## Accéder aux onglets Équipe et Rôles
 
-## Rôles du projet
+Chemin : sélectionner un projet → onglets `Équipe` / `Rôles`.
 
-La page Rôles présente la liste des rôles du projet :
+![Onglets du projet](/img/guide/roles/onglets-projet-v9-roles.png)
+
+## Consulter qui a quoi (onglet Équipe)
+
+L’onglet `Équipe` affiche les membres du projet et les rôles qui leur sont associés.
+
+![Membres du projet et rôles](/img/iam/project-members.png)
+
+La capture ci-dessus illustre un exemple avec un utilisateur de test.
+
+## Gérer les rôles (onglet Rôles)
+
+L’onglet `Rôles` présente la liste des rôles du projet.
 
 ![default](/img/guide/roles/default.png)
 
-Par défaut le rôle `Tout le monde` regroupe tous les membres de l'équipe avec les permissions suivantes :
+Par défaut, le rôle `Tout le monde` regroupe tous les membres de l'équipe avec les permissions suivantes :
 
 - Reprovisionner le projet
 - Voir les environnements
 - Voir les dépôts
 
-## Créer un rôle
+## Créer ou modifier un rôle
 
 Cliquer sur le bouton `Ajouter un rôle`.
 
 ![add_role](/img/guide/roles/add.png)
 
-Le champ de texte `Nom du rôle` permet de choisir le nom du rôle à créer.
+Le champ `Nom du rôle` permet de choisir le nom du rôle à créer.
 
-Détail des permissions :
+### Permissions disponibles
 
 - Projet
   - Gérer le projet : Permet de gérer tout le projet et ses ressources associées
@@ -44,31 +55,57 @@ Détail des permissions :
   - Gérer les dépôts : Permet de créer, éditer, supprimer des dépôts
   - Voir les dépôts : Permet de visualiser tous les dépôts et leurs configurations
 
-Cliquer sur le bouton `Enregistrer` pour créer le rôle.
+Cliquer sur `Enregistrer` pour créer le rôle.
 
-## Assigner/Retirer un membre à un rôle
+### Ajouter/retirer des membres à un rôle
 
-Cliquer sur le rôle voulu et aller dans l'onglet `Membres`
+Après création, sélectionner le rôle puis ouvrir l’onglet `Membres` pour ajouter/retirer des utilisateurs. Les modifications sont sauvegardées automatiquement.
 
-![Menu](/img/guide/roles/membres.png)
+![Membres d’un rôle projet](/img/iam/project-role-members.png)
 
-Dans l'exemple, Aurahan est associé au rôle Dev.
+## Supprimer un rôle
 
-Les modifications concernant les membres d'un rôle sont sauvegardées automatiquement.
+Pour supprimer un rôle, sélectionner celui-ci dans la liste des rôles puis cliquer sur `Supprimer`.
 
-Il est possible de retrouver un récapitulatif des rôles associés aux membres du projet sur la page `Equipes` :
+## Règles importantes
 
-![Menu](/img/guide/roles/recap_membres_projet.png)
+### Cumul des rôles
 
-Ici :
+Les permissions sont cumulatives : un utilisateur obtient l’ensemble des permissions de tous les rôles qui lui sont assignés. Il n’y a pas de mécanisme de “refus” qui viendrait retirer des droits.
 
-- Baptiste est le créateur du projet
-- Pierre a le rôle ops
-- Aurahan a les rôles dev et PO
+Exemple : si un rôle donne `Voir les dépôts` et un autre donne `Gérer les dépôts`, l’utilisateur pourra `Gérer les dépôts`.
 
-## Supprimer un rôle
+### Rôles préconfigurés (lecture seule)
+
+Certains rôles sont fournis par la plateforme (rôles “système”). Ils sont en lecture seule : vous ne pouvez pas modifier leurs permissions ni leur nom, mais vous pouvez ajouter/retirer des membres.
+
+Pour les identifier, vérifier que les champs de paramétrage sont non modifiables (grisés) dans l’interface.
+
+![Paramétrage d’un rôle lecture seule](/img/iam/project-role-readonly.png)
+
+## Vérification dans les services intégrés (exemple GitLab)
+
+La Console est la source de vérité des rôles projet. Selon les intégrations actives et le niveau de synchronisation, l’affectation à un rôle peut se traduire par des droits visibles dans des services externes.
+
+Si aucune intégration externe n’est active, la vérification se fait uniquement dans la Console (onglets `Équipe` et `Rôles`).
+
+À ce jour, GitLab est le service intégré pour ce contrôle.
+
+Correspondance des rôles projet vers GitLab (par défaut) :
+
+| Rôle projet (Console) | Droits GitLab sur le groupe du projet |
+| --- | --- |
+| Administrateur (`/console/admin`) | Maintainer |
+| DevOps (`/console/devops`) | Developer |
+| Développeur (`/console/developer`) | Developer |
+| Lecture seule (`/console/readonly`) | Reporter |
+| Propriétaire du projet (Console) | Owner |
+
+Cette correspondance peut être adaptée par les administrateurs via la configuration du plugin GitLab.
+
+Exemple (GitLab) :
 
-Pour supprimer un rôle, sélectionner celui-ci dans la liste des rôles et cliquer sur le bouton `Supprimer`
+![GitLab - membres du groupe](/img/iam/gitlab-group-members.png)
 
 ## Exemple de rôle
 

docs/platform/iam.md

@@ -0,0 +1,66 @@
+# IAM Console
+
+Cette page présente l’IAM de la Console (Identity & Access Management) : authentification, autorisations et principes de synchronisation des groupes.
+
+## Architecture fonctionnelle
+
+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’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.
+
+La Console reste la source de vérité des droits ; les services externes consomment une projection synchronisée de ces droits selon les intégrations actives.
+
+## Groupes et rôles
+
+La Console maintient une hiérarchie de groupes Keycloak par projet pour matérialiser les rôles et la séparation RO/RW des environnements :
+
+```txt
+/<projectSlug>
+  /console
+    /<role-group-path...>
+    /<environmentName>
+      /RO
+      /RW
+```
+
+La Console maintient ces groupes automatiquement (création des groupes manquants, mise à jour des appartenances et nettoyage des groupes orphelins).
+
+Certains rôles affichés dans la Console sont préconfigurés (rôles “système”) et sont en lecture seule. Dans ce cas, l’interface permet typiquement de gérer les membres, mais pas de modifier le contenu du rôle.
+
+## Parcours
+
+- Rôles plateforme (scope Console) : [Rôles plateforme](/administration/roles)
+- Rôles projet (scope projet) : [Gestion des rôles](/guide/roles)
+
+### Corroboration externe (exemple GitLab)
+
+Selon les intégrations actives et le niveau de synchronisation, on peut corroborer les accès dans les services externes (projets et memberships). À ce jour, GitLab est le service intégré pour ce contrôle.
+
+Voir des exemples de captures dans [Gestion des rôles](/guide/roles) et [Rôles plateforme](/administration/roles).
+
+Pour que cette vérification soit pertinente :
+
+- l’intégration du service concerné doit être active ;
+- le mapping des groupes/rôles doit être configuré pour ce service ;
+- la synchronisation doit être terminée.
+
+## Pour aller plus loin
+
+- [Rôles plateforme](/administration/roles)
+- [Gestion des rôles (projet)](/guide/roles)
+- [Gestion des équipes](/guide/team)
+- [Gestion des projets](/guide/projects-management)
+- [Administration : utilisateurs](/administration/utilisateurs)
+- [Administration : projets](/administration/projets)
+
+## Sécurité
+
+Ne pas renuméroter les bits de `ADMIN_PERMS`/`PROJECT_PERMS` sans migration contrôlée. Les cookies de session doivent rester `httpOnly` + `secure` en production (HTTPS). Les jetons API sont stockés hashés et doivent être traités comme des secrets.
+
+Contrôles opératoires recommandés :
+
+- vérifier régulièrement les rôles à privilèges élevés ;
+- valider les appartenances aux groupes synchronisés ;
+- auditer périodiquement les jetons API actifs.