From dceea29e9b6b695afccd86df71cebe93e2247403 Mon Sep 17 00:00:00 2001 From: William Phetsinorath Date: Wed, 14 Oct 2026 12:29:33 +0200 Subject: [PATCH] doc: ajouter la fiche RBAC GitLab et consolider la correspondance Fiche guide/rbac/gitlab : mapping des niveaux selon apps/server-nestjs (gitlab.constants.ts, gitlab.utils.ts generateAccessLevelMapping) : admin/devops -> Maintainer, developer -> Developer, readonly/security -> Reporter, defaut sans groupe OIDC -> Guest, flags admin/auditor GitLab pour les groupes plateforme, tableau des cles de configuration avec les valeurs par defaut. Consolidation : les sections GitLab des pages roles (administration + guide) repetaient un mapping perime (devops -> Developer) et l'avertissement 9.16.x obsolete ; suppression au profit d'un renvoi vers la fiche. La purge est precisee : suppression seulement si purge = enabled, sinon signalement dans les journaux. Co-authored-by: Automata Signed-off-by: William Phetsinorath Change-Id: I2efa5c8a54b0b54d13767fe4eb2ba15d6a6a6964 --- docs/.vitepress/sidebar.json | 4 +++ docs/administration/roles.md | 52 +------------------------------ docs/guide/rbac/gitlab.md | 60 ++++++++++++++++++++++++++++++++++++ docs/guide/roles.md | 32 +++---------------- 4 files changed, 69 insertions(+), 79 deletions(-) create mode 100644 docs/guide/rbac/gitlab.md diff --git a/docs/.vitepress/sidebar.json b/docs/.vitepress/sidebar.json index 2d085f7..2184a86 100644 --- a/docs/.vitepress/sidebar.json +++ b/docs/.vitepress/sidebar.json @@ -144,6 +144,10 @@ { "text": "Grafana", "link": "/guide/rbac/grafana" + }, + { + "text": "GitLab", + "link": "/guide/rbac/gitlab" } ] }, diff --git a/docs/administration/roles.md b/docs/administration/roles.md index d48421f..761781a 100644 --- a/docs/administration/roles.md +++ b/docs/administration/roles.md @@ -31,58 +31,8 @@ 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 | -| --- | --- | -| `//console/admin` | Maintainer | -| `//console/devops` | Developer | -| `//console/developer` | Developer | -| `//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 | - -:::warning -**Phase de rétrocompatibilité (9.16.x)** — **GitLab** attribue toujours le rôle `Développeur` par défaut lors de l'ajout d'un membre. Le rôle `Lecture seule` de la Console (`/console/readonly`, normalement dédié aux personnes chargés de faire des rapports ou des audits) n'a donc aucun effet sur **Gitlab**. Ce comportement est conservé temporairement pour compatibilité ; Il évoluera vers le rôle **Gitlab** `Invité` dans une prochaine version. -::: - -:::danger -**Changement cassant** — Les rôles sont désormais provisionnés de manière autoritaire dans les services intégrés (GitLab). La Console prend le contrôle total de l'appartenance : tout membre non tracé par la Console sera **supprimé**, et seuls les membres assignés via les rôles Console seront **ajoutés**. Ce comportement empêche toute dérive entre la Console et les services externes. Les modifications manuelles de membership dans GitLab seront écrasées lors de la synchronisation. -::: - ## Voir aussi +- [Groupes Keycloak et GitLab](/guide/rbac/gitlab) - [Gestion des rôles (projet)](/guide/roles) - [Utilisateurs](/administration/utilisateurs) diff --git a/docs/guide/rbac/gitlab.md b/docs/guide/rbac/gitlab.md new file mode 100644 index 0000000..58a6a5b --- /dev/null +++ b/docs/guide/rbac/gitlab.md @@ -0,0 +1,60 @@ +# Groupes Keycloak et GitLab + +Ce document décrit comment la Console propage les **groupes Keycloak** en **niveaux d'accès GitLab** (membres du groupe du projet), et quels droits en résultent. + +## Vue par rôle + +Ce que chaque rôle Console obtient réellement dans GitLab : + +| Rôle Console | Groupe Keycloak | Accès obtenu dans GitLab | +| --------------------- | --------------------------- | ---------------------------- | +| Propriétaire projet | — | **Owner** sur le groupe | +| Administrateur projet | `//console/admin` | **Maintainer** sur le groupe | +| DevOps | `//console/devops` | **Maintainer** sur le groupe | +| Développeur | `//console/developer` | **Developer** sur le groupe | +| Lecture seule | `//console/readonly` | **Reporter** sur le groupe | +| Security | `//console/security` | **Reporter** sur le groupe | +| Admin plateforme | `/console/admin` | **Admin GitLab** (flag instance) | +| Audit plateforme | `/console/readonly`, `/console/security` | **Auditeur GitLab** (flag auditor) | + +## 1. Authentification : GitLab via OIDC Keycloak + +- GitLab est fédéré au fournisseur OIDC Keycloak ; les utilisateurs se connectent sans mot de passe local. +- La Console approvisionne, pour chaque projet, le **groupe GitLab** et y ajoute les membres avec un niveau d'accès (Owner / Maintainer / Developer / Reporter / Guest). + +## 2. Groupes Keycloak et niveau GitLab résultant + +| Groupe Keycloak | Niveau GitLab | +| --------------------------- | --------------- | +| `//console/admin` | **Maintainer** | +| `//console/devops` | **Maintainer** | +| `//console/developer` | **Developer** | +| `//console/readonly` | **Reporter** | +| `//console/security` | **Reporter** | + +- **Propriétaire du projet** : **Owner** (toujours le niveau le plus élevé, indépendamment des rôles). +- **Cumul des rôles** : en cas de rôles multiples, le **niveau le plus élevé** l'emporte. +- **Rôle sans groupe OIDC reconnu** : le membre reçoit **Guest** (accès minimal au groupe). +- **Rôles plateforme** : les membres d'`/console/admin` reçoivent le flag GitLab **admin** (administration de l'instance) ; les membres des groupes d'audit (`/console/readonly`, `/console/security`) reçoivent le flag **auditor** (lecture sur toute l'instance). +### Adaptation par configuration du plugin GitLab + +| Clé | Rôle | Valeur par défaut | +| ------------------------------------ | --------------------------------------- | --------------------------------- | +| `projectMaintainerGroupPathSuffix` | Suffixes OIDC donnant l'accès **Maintainer** | `/console/admin,/console/devops` | +| `projectDeveloperGroupPathSuffix` | Suffixe OIDC donnant l'accès **Developer** | `/console/developer` | +| `projectReporterGroupPathSuffix` | Suffixes OIDC donnant l'accès **Reporter** | `/console/readonly,/console/security` | +| `adminGroupPath` | Groupe OIDC donnant le flag **admin** GitLab | `/console/admin` | +| `auditorGroupPath` | Groupes OIDC donnant le flag **auditor** GitLab | `/console/readonly,/console/security` | + +## 3. Points d'attention + +- **Provisionnement autoritaire.** La Console aligne systématiquement le niveau d'accès de chaque membre tracé : les modifications manuelles dans GitLab sont écrasées à la synchronisation. Les membres non tracés par la Console sont **supprimés** uniquement lorsque la purge est activée (config plugin `purge` = `enabled`) ; sinon ils sont seulement signalés dans les journaux. +- Les dépôts `infra-apps` et `mirror` sont des dépôts techniques Console, jamais des cibles de mirroring. + +## 4. Qui gère quoi ? + +| Élément | Géré par | +| ---------------------------------- | ------------------------- | +| Identité OIDC / groupes Keycloak | **Keycloak** | +| Groupes GitLab, membres & niveaux | **Console** (automatique) | +| Application des droits | **GitLab** | diff --git a/docs/guide/roles.md b/docs/guide/roles.md index c9f8ae9..5283e2f 100644 --- a/docs/guide/roles.md +++ b/docs/guide/roles.md @@ -83,37 +83,13 @@ Pour les identifier, vérifier que les champs de paramétrage sont non modifiabl ![Paramétrage d’un rôle lecture seule](/img/iam/project-role-readonly.png) -## Vérification dans les services intégrés (exemple GitLab) +## Vérification dans les services intégrés -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. +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`). +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. - -:::warning -**Phase de rétrocompatibilité (9.16.x)** — **GitLab** attribue toujours le rôle `Développeur` par défaut lors de l'ajout d'un membre. Le rôle `Lecture seule` de la Console (`/console/readonly`, normalement dédié aux personnes chargés de faire des rapports ou des audits) n'a donc aucun effet sur **Gitlab**. Ce comportement est conservé temporairement pour compatibilité ; Il évoluera vers le rôle **Gitlab** `Invité` dans une prochaine version. -::: - -:::danger -**Changement cassant** — Les rôles sont désormais provisionnés de manière autoritaire dans les services intégrés (GitLab). La Console prend le contrôle total de l'appartenance : tout membre non tracé par la Console sera **supprimé**, et seuls les membres assignés via les rôles Console seront **ajoutés**. Ce comportement empêche toute dérive entre la Console et les services externes. Les modifications manuelles de membership dans GitLab seront écrasées lors de la synchronisation. -::: - -Exemple (GitLab) : - -![GitLab - membres du groupe](/img/iam/gitlab-group-members.png) +À ce jour, GitLab est le service intégré pour ce contrôle : la correspondance groupes Keycloak → niveaux d'accès est détaillée dans la fiche [Groupes Keycloak et GitLab](/guide/rbac/gitlab). ## Exemple de rôle