Merge pull request #95 from linagora/feat/manage-groups

Implement supplementary groups synchronization (#38)

Author: guimard

README.md

@@ -32,6 +32,11 @@ The module supports two authentication methods:
   - Auto-create Unix accounts on first login
   - Configurable shell, home directory, UID/GID ranges
   - Skeleton directory support
+- **[Group synchronization](doc/llng-configuration.md#group-synchronization)**:
+  - Sync Unix supplementary groups from LLNG on each login
+  - Automatic group creation if needed
+  - Local whitelist for defense-in-depth (`allowed_managed_groups`)
+  - Groups outside managed pool are never modified
 - **[Service accounts](doc/service-accounts.md)** (ansible, backup, etc.):
   - SSH key authentication without OIDC
   - Per-server configuration file

doc/configuration.md

@@ -45,6 +45,11 @@ rate_limit_max_attempts = 5
 rate_limit_initial_lockout = 30
 rate_limit_max_lockout = 3600
 
+# Group synchronization (#38)
+# Local whitelist of groups allowed to be managed (optional, defense-in-depth)
+# If configured, only groups in this list AND in LLNG's managed_groups will be synced
+# allowed_managed_groups = docker,developers,readonly
+
 # Webhook notifications (optional)
 # notify_enabled = true
 # notify_url = https://alerts.example.com/webhook

doc/llng-configuration.md

@@ -51,22 +51,23 @@ Additional and optional parameters that can be inserted into `lemonldap-ng.ini`,
 
 ### General Parameters
 
-| Parameter                                       | Default      | Description                             |
-| ----------------------------------------------- | ------------ | --------------------------------------- |
-| `oidcServiceDeviceAuthorizationExpiration`      | `600` (10mn) | Device authorization expiration time    |
-| `oidcServiceDeviceAuthorizationPollingInterval` | `5`          | Polling interval in seconds             |
-| `oidcServiceDeviceAuthorizationUserCodeLength`  | `8`          | Length of user code                     |
-| `portalDisplayPamAccess`                        | `0`          | Set to 1 (or a rule) to display PAM tab |
-| `pamAccessRp`                                   | `pam-access` | OIDC Relying Party name                 |
-| `pamAccessTokenDuration`                        | `600` (10mn) | Token duration                          |
-| `pamAccessMaxDuration`                          | `3600` (1h)  | Maximum token duration                  |
-| `pamAccessExportedVars`                         | `{}`         | Exported variables                      |
-| `pamAccessOfflineTtl`                           | `86400` (1d) | Offline cache TTL                       |
-| `pamAccessSshRules`                             | `{}`         | SSH access rules                        |
-| `pamAccessServerGroups`                         | `{}`         | Server groups configuration             |
-| `pamAccessSudoRules`                            | `{}`         | Sudo rules                              |
-| `pamAccessOfflineEnabled`                       | `0`          | Enable offline mode                     |
-| `pamAccessHeartbeatInterval`                    | `300` (5mn)  | Heartbeat interval                      |
+| Parameter                                       | Default      | Description                                                                                        |
+| ----------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| `oidcServiceDeviceAuthorizationExpiration`      | `600` (10mn) | Device authorization expiration time                                                               |
+| `oidcServiceDeviceAuthorizationPollingInterval` | `5`          | Polling interval in seconds                                                                        |
+| `oidcServiceDeviceAuthorizationUserCodeLength`  | `8`          | Length of user code                                                                                |
+| `portalDisplayPamAccess`                        | `0`          | Set to 1 (or a rule) to display PAM tab                                                            |
+| `pamAccessRp`                                   | `pam-access` | OIDC Relying Party name                                                                            |
+| `pamAccessTokenDuration`                        | `600` (10mn) | Token duration                                                                                     |
+| `pamAccessMaxDuration`                          | `3600` (1h)  | Maximum token duration                                                                             |
+| `pamAccessExportedVars`                         | `{}`         | Exported variables                                                                                 |
+| `pamAccessOfflineTtl`                           | `86400` (1d) | Offline cache TTL                                                                                  |
+| `pamAccessSshRules`                             | `{}`         | SSH access rules                                                                                   |
+| `pamAccessServerGroups`                         | `{}`         | Server groups configuration                                                                        |
+| `pamAccessSudoRules`                            | `{}`         | Sudo rules                                                                                         |
+| `pamAccessOfflineEnabled`                       | `0`          | Enable offline mode                                                                                |
+| `pamAccessHeartbeatInterval`                    | `300` (5mn)  | Heartbeat interval                                                                                 |
+| `pamAccessManagedGroups`                        | `{}`         | Unix groups managed by LLNG per server group (see [Group Synchronization](#group-synchronization)) |
 
 When offline mode is enabled, the server-side cache is protected by
 [Cache Brute-Force Protection](security.md#cache-brute-force-protection).
@@ -179,6 +180,87 @@ Or during enrollment:
 sudo ob-enroll -g production
 ```
 
+## Group Synchronization
+
+The group synchronization feature (#38) allows LemonLDAP::NG to manage Unix supplementary groups on target servers. When a user connects via SSH, their Unix groups are synchronized with the groups defined in LLNG.
+
+### Configuration
+
+In `lemonldap-ng.ini`, configure which groups LLNG should manage for each server group:
+
+```perl
+pamAccessManagedGroups = {
+    production => 'docker,developers,readonly',
+    staging => 'developers,testers',
+    bastion => 'operators,auditors',
+    default => ''
+}
+```
+
+- Groups listed in `pamAccessManagedGroups` will be created automatically on the server if they don't exist
+- Users are added to groups they're assigned to in LLNG
+- Users are removed from managed groups they're no longer assigned to in LLNG
+- Groups NOT in `pamAccessManagedGroups` are never modified (local groups are preserved)
+
+### How It Works
+
+```mermaid
+sequenceDiagram
+    participant Client as SSH Client
+    participant Server as Server (PAM)
+    participant LLNG as LemonLDAP::NG
+
+    Client->>Server: ssh user@server
+    Server->>LLNG: /pam/authorize
+    LLNG-->>Server: {groups: ["dev","docker"],<br/>managed_groups: ["dev","docker","qa"]}
+    Note over Server: Filter by local whitelist<br/>(if configured)
+    Note over Server: Sync groups:<br/>• Add user to "dev", "docker"<br/>• Remove from "qa" (managed but not assigned)
+    Server-->>Client: Session established
+```
+
+### Security Considerations
+
+- **Principle of least privilege**: Don't include privileged groups (sudo, wheel, admin) in `managed_groups`
+- **Audit trail**: All group modifications are logged with event type `GROUP_SYNC`
+- **Offline behavior**: Group sync uses cached group information when LLNG is unreachable
+- **File protection**: Group modifications use system tools (`groupadd`, `gpasswd`) which handle `/etc/group` and `/etc/gshadow` atomically
+
+### Local Whitelist (Defense-in-Depth)
+
+Administrators can optionally configure a local whitelist of groups allowed to be managed on each server. This provides defense-in-depth by restricting which groups LLNG can actually modify, regardless of what `managed_groups` it sends.
+
+In `/etc/open-bastion/openbastion.conf`:
+
+```ini
+# Only allow these groups to be managed by LLNG on this server
+allowed_managed_groups = docker,developers,readonly
+```
+
+When configured:
+
+- Groups must be in BOTH `pamAccessManagedGroups` (from LLNG) AND `allowed_managed_groups` (local) to be synced
+- Groups sent by LLNG but not in the local whitelist are silently ignored
+- This allows local administrators to have final control over which groups can be managed
+
+**Use cases:**
+
+- Restrict LLNG to manage only specific groups on sensitive servers
+- Allow different group policies per server even within the same server group
+- Provide a safety net against misconfigured LLNG policies
+
+### Example: Per-Environment Groups
+
+```perl
+# Developer groups differ by environment
+pamAccessManagedGroups = {
+    production => 'app-users,readonly',           # Read-only in prod
+    staging => 'app-users,developers,docker',     # Full dev access in staging
+    bastion => 'operators'                        # Bastion operators only
+}
+```
+
+When a user moves from staging to production access, their docker and developers group memberships are automatically removed on production servers.
+
 ## See Also
 
 - [PAM Authentication Modes](pam-modes.md) - Configure PAM on servers

doc/security/02-ssh-connection.md

@@ -1243,6 +1243,77 @@ cache_rate_limit_max_lockout_sec = 3600 # 1 heure max
 
 ---
 
+### R-S13 - Manipulation des groupes Unix via synchronisation LLNG
+
+|                 | Score |
+| --------------- | :---: |
+| **Probabilité** |   2   |
+| **Impact**      |   3   |
+
+**Architectures concernées :** A, B, C, D (avec synchronisation de groupes activée)
+
+**Description :** La fonctionnalité de synchronisation des groupes Unix (#38) permet à LLNG de gérer les groupes supplémentaires des utilisateurs sur les serveurs. Un attaquant pourrait exploiter cette fonctionnalité pour obtenir des privilèges supplémentaires.
+
+**Vecteurs d'attaque :**
+
+- Modification des groupes côté LLNG pour obtenir des accès (ex: groupe docker, wheel, admin)
+- Attaque MITM sur la communication PAM-LLNG pour injecter des groupes
+- Modification du cache offline pour ajouter des groupes non autorisés
+- Symlink attack sur /etc/group pendant la modification
+
+**Conséquence :** Un attaquant pourrait obtenir des privilèges supplémentaires sur le serveur (sudo, docker, accès à des ressources sensibles).
+
+**Remédiation embarquée (IMPLÉMENTÉE) :**
+
+Le module PAM implémente plusieurs contrôles de sécurité :
+
+| Mesure de sécurité             | Description                                                                   |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| **Groupes gérés explicites**   | Seuls les groupes listés dans `managed_groups` peuvent être modifiés          |
+| **Liste blanche locale**       | `allowed_managed_groups` permet de restreindre davantage côté serveur         |
+| **Validation des noms**        | Les noms de groupes sont validés (alphanum, tiret, underscore uniquement)     |
+| **Utilisation outils système** | `groupadd`/`gpasswd` pour manipulation atomique de /etc/group et /etc/gshadow |
+| **Cache chiffré**              | Les groupes sont stockés en cache avec AES-256-GCM                            |
+| **Audit GROUP_SYNC**           | Toutes les modifications de groupes sont journalisées                         |
+
+**Configuration LLNG (server-side) :**
+
+```yaml
+# Configuration LLNG Manager
+pamAccessManagedGroups:
+  production: "docker,developers,readonly"
+  bastion: "operators,auditors"
+  default: "" # Pas de sync par défaut
+```
+
+**Configuration locale (defense-in-depth) :**
+
+```ini
+# /etc/open-bastion/openbastion.conf
+# Liste blanche locale optionnelle - restreint les groupes que LLNG peut gérer
+allowed_managed_groups = docker,developers,readonly
+```
+
+La liste blanche locale offre une défense en profondeur :
+
+- Les groupes doivent être dans LLNG `managed_groups` ET dans `allowed_managed_groups` local
+- Permet aux administrateurs serveur de contrôler ce que LLNG peut modifier
+- Protection contre une configuration LLNG erronée ou compromise
+
+**Principe de moindre privilège :**
+
+- Ne pas inclure les groupes critiques (wheel, sudo, root, admin) dans `managed_groups`
+- Créer des groupes dédiés pour les accès applicatifs (ex: app-users, db-readers)
+- Utiliser des `server_group` différents pour segmenter les accès
+- Configurer `allowed_managed_groups` sur les serveurs sensibles
+
+|                 |                                Score résiduel                                |
+| --------------- | :--------------------------------------------------------------------------: |
+| **Probabilité** | 1 (avec managed_groups restrictifs, liste blanche locale et validation noms) |
+| **Impact**      |                       2 (groupes critiques non gérés)                        |
+
+---
+
 ## 12. Comptes de Service
 
 ### Description

include/audit_log.h

@@ -30,7 +30,8 @@ typedef enum {
     AUDIT_ENROLLMENT_START,
     AUDIT_ENROLLMENT_SUCCESS,
     AUDIT_ENROLLMENT_FAILURE,
-    AUDIT_USER_CREATED
+    AUDIT_USER_CREATED,
+    AUDIT_GROUP_SYNC
 } audit_event_type_t;
 
 /* Audit event structure */

include/auth_cache.h

@@ -18,12 +18,14 @@
 
 /* Authorization cache entry */
 typedef struct {
-    int version;            /* Cache format version (3) */
+    int version;            /* Cache format version (4) */
     time_t expires_at;      /* Expiration timestamp */
     char *user;             /* Username */
     bool authorized;        /* Authorization result */
     char **groups;          /* User groups */
     size_t groups_count;    /* Number of groups */
+    char **managed_groups;      /* Pool of groups managed by LLNG */
+    size_t managed_groups_count;
     bool sudo_allowed;      /* Sudo permission */
     bool sudo_nopasswd;     /* Sudo without password */
     char *gecos;            /* Full name / GECOS */

include/config.h

@@ -140,6 +140,9 @@ typedef struct {
     int cache_rate_limit_max_attempts;     /* Max failed lookups before lockout (default: 3) */
     int cache_rate_limit_lockout_sec;      /* Initial lockout in seconds (default: 60) */
     int cache_rate_limit_max_lockout_sec;  /* Maximum lockout in seconds (default: 3600) */
+
+    /* Group synchronization (#38) */
+    char *allowed_managed_groups;          /* Comma-separated whitelist of groups allowed to be managed locally (optional) */
 } pam_openbastion_config_t;
 
 /*

include/ob_client.h

@@ -38,6 +38,8 @@ typedef struct {
     char *user;
     char **groups;
     size_t groups_count;
+    char **managed_groups;      /* Pool of groups managed by LLNG for this server */
+    size_t managed_groups_count;
     char *reason;
     int expires_in;
     bool active;  /* For introspection */

include/str_utils.h

@@ -37,6 +37,60 @@ static inline char *str_json_strdup(struct json_object *obj)
     const char *str = json_object_get_string(obj);
     return str ? strdup(str) : NULL;
 }
+
+/*
+ * Parse a JSON array of strings into a dynamically allocated string array.
+ * Only string elements are copied; non-strings are skipped.
+ * Returns the array on success (caller must free each element and the array),
+ * NULL on failure or empty array.
+ * Sets *out_count to the number of valid strings copied.
+ */
+static inline char **str_json_parse_string_array(struct json_object *arr,
+                                                  size_t max_count,
+                                                  size_t *out_count)
+{
+    *out_count = 0;
+
+    if (!arr || !json_object_is_type(arr, json_type_array)) {
+        return NULL;
+    }
+
+    size_t count = json_object_array_length(arr);
+    if (count > max_count) {
+        count = max_count;
+    }
+    if (count == 0) {
+        return NULL;
+    }
+
+    char **result = calloc(count + 1, sizeof(char *));
+    if (!result) {
+        return NULL;
+    }
+
+    size_t valid_count = 0;
+    for (size_t i = 0; i < count; i++) {
+        struct json_object *elem = json_object_array_get_idx(arr, i);
+        /* Only accept string elements, skip non-strings */
+        if (elem && json_object_is_type(elem, json_type_string)) {
+            const char *str = json_object_get_string(elem);
+            if (str) {
+                result[valid_count] = strdup(str);
+                if (result[valid_count]) {
+                    valid_count++;
+                }
+            }
+        }
+    }
+
+    if (valid_count == 0) {
+        free(result);
+        return NULL;
+    }
+
+    *out_count = valid_count;
+    return result;
+}
 #endif
 
 /*