[SONiC] Implement comprehensive local user management system

manoharan-nexthop · manoharan-nexthop · commit df7a45819f7c · 2025-09-29T21:10:15.000+05:30
SONiC currently lacks a comprehensive local user management system that can:
- Manage users through CONFIG_DB with role-based access control
- Provide secure password hashing and authentication policies
- Support SSH key management and PAM integration
- Enable/disable users dynamically without system restarts
- Integrate with SONiC's configuration management framework

This implementation addresses the User Management HLD requirements for centralized user administration in SONiC.

**1. YANG Model &amp; Configuration Schema:**
- Added sonic-user.yang model defining LOCAL_USER and LOCAL_ROLE_SECURITY_POLICY tables
- Integrated user management into CONFIG_DB schema with role-based configuration
- Added DEVICE_METADATA.local_user_management feature flag

**2. User Management Daemon (userd):**
- Implemented C++ daemon using SWSS framework for CONFIG_DB integration
- Added comprehensive user lifecycle management (create/update/delete/enable/disable)
- Implemented role-based group assignment (administrator, operator roles)
- Added SSH key management with proper file permissions
- Integrated PAM faillock configuration using Jinja2 templates
- Used posix_spawn() for secure command execution without shell interpretation
- Added efficient change detection to avoid unnecessary system calls

**3. CLI Interface:**
- Extended sonic-utilities with 'config user' and 'show user' commands
- Added user import functionality to migrate existing system users
- Implemented secure password hashing using system's default method (yescrypt/SHA-512)
- Added role-based user management with proper validation

**4. Build System Integration:**
- Added sonic-host-services package with userd daemon and systemd service
- Integrated user management into SONiC image build process
- Added template-based configuration generation for init_cfg.json
- Added build dependencies for JSON processing and password hashing

**5. Security &amp; Authentication:**
- Implemented secure password storage using system's native hashing
- Added PAM faillock integration for login attempt limiting
- Proper file permissions for SSH keys and user directories
- Role-based access control with predefined group assignments

**1. Basic User Management:**
```bash
sudo config user add testuser --role administrator --password-prompt

show user

sudo config user modify --enabled testuser
sudo config user modify --disabled testuser

sudo config user delete testuser
```

**2. Import Existing Users:**
```bash
sudo config user import-existing
```

**3. SSH Key Management:**
```bash
sudo config user add-ssh-key testuser "ssh-rsa AAAAB3NzaC1yc2E..."

sudo config user remove-ssh-key testuser "ssh-rsa AAAAB3NzaC1yc2E..."
```

**4. Verify Configuration:**
```bash
redis-cli -n 4 hgetall "LOCAL_USER|testuser"
redis-cli -n 4 hget "DEVICE_METADATA|localhost" local_user_management

getent passwd testuser
sudo cat /etc/shadow | grep testuser
groups testuser
```

**5. Verify Daemon Operation:**
```bash
systemctl status userd

journalctl -u userd -f

cat /etc/security/faillock.conf
```

**6. Test Authentication:**
```bash
su - testuser

ssh testuser@localhost
```

The implementation provides a complete user management solution integrated with SONiC's configuration framework, supporting both CLI and programmatic management of local users with proper security controls.
diff --git a/build_debian.sh b/build_debian.sh
@@ -320,6 +320,7 @@ fi
 ## Note: ca-certificates is needed for easy_install
 ## Note: don't install python-apt by pip, older than Debian repo one
 ## Note: fdisk and gpg are needed by fwutil
+## Note: whois is needed for mkpasswd by sonic-utilities
 sudo LANG=C DEBIAN_FRONTEND=noninteractive chroot $FILESYSTEM_ROOT apt-get -y install      \
     file                    \
     ifmetric                \
@@ -386,7 +387,8 @@ sudo LANG=C DEBIAN_FRONTEND=noninteractive chroot $FILESYSTEM_ROOT apt-get -y in
     wireless-regdb          \
     ethtool                 \
     zstd                    \
-    nvme-cli
+    nvme-cli                \
+    whois
 
 sudo cp files/initramfs-tools/pzstd $FILESYSTEM_ROOT/etc/initramfs-tools/hooks/pzstd
 sudo chmod +x $FILESYSTEM_ROOT/etc/initramfs-tools/hooks/pzstd
diff --git a/files/build_templates/init_cfg.json.j2 b/files/build_templates/init_cfg.json.j2
@@ -5,6 +5,7 @@
             {%- if include_p4rt == "y" %}"synchronous_mode":"enable",{% endif %}
             "default_bgp_status": {% if shutdown_bgp_on_start == "y" %}"down"{% else %}"up"{% endif %},
             "default_pfcwd_status": {% if enable_pfcwd_on_start == "y" %}"enable"{% else %}"disable"{% endif %},
+            "local_user_management": {%- if sonicadmin_user and sonicadmin_password %}"enabled"{% else %}"disabled"{% endif %},
             "timezone": "UTC"
         }
     },
@@ -203,6 +204,15 @@
             "num_dumps": "3"
         }
     },
+{%- if sonicadmin_user and sonicadmin_password %}
+    "LOCAL_USER": {
+        "{{ sonicadmin_user }}": {
+            "role": "administrator",
+            "password_hash": "{{ sonicadmin_password }}",
+            "enabled": "true"
+        }
+    },
+{%- endif %}
     "NTP": {
         "global": {
             "authentication": "disabled",
diff --git a/files/build_templates/sonic_debian_extension.j2 b/files/build_templates/sonic_debian_extension.j2
@@ -346,6 +346,8 @@ install_deb_package {{deb}}
 # Install sonic-db-cli
 install_deb_package $debs_path/sonic-db-cli_*.deb
 
+# Install SONiC host userd package
+install_deb_package $debs_path/sonic-host-userd_*.deb
 
 {% if include_system_eventd == "y" and build_reduce_image_size != "y" %}
 # Install sonic-rsyslog-plugin
@@ -635,7 +637,7 @@ echo "config-topology.service" | sudo tee -a $GENERATED_SERVICE_FILE
 sudo cp $IMAGE_CONFIGS/config-topology/config-topology.sh $FILESYSTEM_ROOT/usr/bin
 
 # Generate initial SONiC configuration file
-j2 files/build_templates/init_cfg.json.j2 | sudo tee $FILESYSTEM_ROOT/etc/sonic/init_cfg.json
+sonicadmin_password="$(sudo grep ^${sonicadmin_user} $FILESYSTEM_ROOT/etc/shadow | cut -d: -f2)" j2 files/build_templates/init_cfg.json.j2 | sudo tee $FILESYSTEM_ROOT/etc/sonic/init_cfg.json
 
 # Copy config-setup script, conf file and service file
 j2 files/build_templates/config-setup.service.j2 | sudo tee $FILESYSTEM_ROOT_USR_LIB_SYSTEMD_SYSTEM/config-setup.service
diff --git a/platform/vs/docker-sonic-vs.mk b/platform/vs/docker-sonic-vs.mk
@@ -12,6 +12,7 @@ $(DOCKER_SONIC_VS)_DEPENDS += $(SYNCD_VS) \
                               $(LIBYANG_PY3) \
                               $(SONIC_UTILITIES_DATA) \
                               $(SONIC_HOST_SERVICES_DATA) \
+                              $(SONIC_HOST_USERD) \
                               $(SYSMGR)
 
 $(DOCKER_SONIC_VS)_PYTHON_WHEELS += $(SONIC_PY_COMMON_PY3) \
diff --git a/platform/vs/docker-sonic-vs/Dockerfile.j2 b/platform/vs/docker-sonic-vs/Dockerfile.j2
@@ -34,6 +34,8 @@ RUN apt-get install -y net-tools \
                        iptables \
                        jq \
                        uuid-dev \
+                       # For using mkpasswd by sonic-utilities
+                       whois \
                        # For installing Python m2crypto package
                        # (these can be uninstalled after installation)
                        build-essential \
diff --git a/rules/sonic-host-services.dep b/rules/sonic-host-services.dep
@@ -1,7 +1,7 @@
 SPATH       := $($(SONIC_HOST_SERVICES_PY3)_SRC_PATH)
 DEP_FILES   := $(SONIC_COMMON_FILES_LIST) rules/sonic-host-services.mk rules/sonic-host-services.dep
 DEP_FILES   += $(SONIC_COMMON_BASE_FILES_LIST)
-SMDEP_FILES := $(addprefix $(SPATH)/,$(shell git -C $(SPATH) ls-files | grep -v ^data))
+SMDEP_FILES := $(addprefix $(SPATH)/,$(shell git -C $(SPATH) ls-files | grep -v ^data | grep -v ^userd))
 
 $(SONIC_HOST_SERVICES_PY3)_CACHE_MODE  := GIT_CONTENT_SHA
 $(SONIC_HOST_SERVICES_PY3)_DEP_FLAGS   := $(SONIC_COMMON_FLAGS_LIST)
diff --git a/rules/sonic-host-userd.dep b/rules/sonic-host-userd.dep
@@ -0,0 +1,8 @@
+SPATH       := $($(SONIC_HOST_USERD)_SRC_PATH)
+DEP_FILES   := $(SONIC_COMMON_FILES_LIST) rules/sonic-host-userd.mk rules/sonic-host-userd.dep
+DEP_FILES   += $(SONIC_COMMON_BASE_FILES_LIST)
+DEP_FILES   += $(addprefix $(SPATH)/,$(shell git -C $(SPATH) ls-files))
+
+$(SONIC_HOST_USERD)_CACHE_MODE  := GIT_CONTENT_SHA
+$(SONIC_HOST_USERD)_DEP_FLAGS   := $(SONIC_COMMON_FLAGS_LIST)
+$(SONIC_HOST_USERD)_DEP_FILES   := $(DEP_FILES)
diff --git a/rules/sonic-host-userd.mk b/rules/sonic-host-userd.mk
@@ -0,0 +1,7 @@
+# SONiC host userd binary package
+
+SONIC_HOST_USERD = sonic-host-userd_1.0-1_$(CONFIGURED_ARCH).deb
+$(SONIC_HOST_USERD)_SRC_PATH = $(SRC_PATH)/sonic-host-services/userd
+$(SONIC_HOST_USERD)_DEPENDS += $(LIBSWSSCOMMON_DEV)
+$(SONIC_HOST_USERD)_RDEPENDS += $(SONIC_HOST_SERVICES_DATA) $(LIBSWSSCOMMON)
+SONIC_DPKG_DEBS += $(SONIC_HOST_USERD)
diff --git a/slave.mk b/slave.mk
@@ -1398,6 +1398,7 @@ $(addprefix $(TARGET_PATH)/, $(SONIC_INSTALLERS)) : $(TARGET_PATH)/% : \
                 $(SONIC_UTILITIES_DATA) \
                 $(SONIC_CTRMGRD_RS) \
                 $(SONIC_HOST_SERVICES_DATA) \
+                $(SONIC_HOST_USERD) \
                 $(BASH) \
                 $(BASH_TACPLUS) \
                 $(AUDISP_TACPLUS) \
diff --git a/src/sonic-yang-models/setup.py b/src/sonic-yang-models/setup.py
@@ -147,6 +147,7 @@
     'sonic-smart-switch.yang',
     'sonic-spanning-tree.yang',
     'sonic-srv6.yang',
+    'sonic-user.yang',
 ]
 
 class my_build_py(build_py):
diff --git a/src/sonic-yang-models/tests/files/sample_config_db.json b/src/sonic-yang-models/tests/files/sample_config_db.json
@@ -3133,6 +3133,13 @@
                     "OUT_CURR_OCCUPANCY_BYTES"
                 ]
             }
+        },
+        "LOCAL_USER": {
+            "admin": {
+                "role": "administrator",
+                "password_hash": "$y$j9T$mYVqMrB/TF29nNg.IK63H1$4k1Th1bqfrLXo50z3.KJvsKpffgD7NPMExVmDTrnUc8",
+                "enabled": "true"
+            }
         }
     },
     "SAMPLE_CONFIG_DB_UNKNOWN": {
diff --git a/src/sonic-yang-models/yang-models/sonic-device_metadata.yang b/src/sonic-yang-models/yang-models/sonic-device_metadata.yang
@@ -116,6 +116,16 @@ module sonic-device_metadata {
                     }
                 }
 
+                leaf local_user_management {
+                    type enumeration {
+                        enum enabled;
+                        enum disabled;
+                    }
+                    default disabled;
+                    description "Enable or disable local user management feature.
+                                 When enabled, the system will manage local users through the LOCAL_USER table.";
+                }
+
                 leaf frr_mgmt_framework_config {
                     type boolean;
                     description "FRR configurations are handled by sonic-frr-mgmt-framework module when set to true,
diff --git a/src/sonic-yang-models/yang-models/sonic-user.yang b/src/sonic-yang-models/yang-models/sonic-user.yang
@@ -0,0 +1,102 @@
+module sonic-user {
+    yang-version 1.1;
+    namespace "http://github.com/sonic-net/sonic-user";
+    prefix "sonic-user";
+
+    description "SONIC User Management YANG Module";
+
+    revision 2025-09-12 {
+        description "Initial revision for declarative user management";
+    }
+
+    // Common typedef for user roles
+    typedef user-role {
+        type enumeration {
+            enum "administrator" {
+                description "Grants administrative privileges (e.g., member of sudo, docker, admin, redis groups).";
+            }
+            enum "operator" {
+                description "Grants operator-level (read-only or limited) privileges.";
+            }
+        }
+        description "User role that determines group memberships, privileges, and applicable security policies.";
+    }
+
+    // Top-level container for the User feature
+    container sonic-user {
+        description "Top-level container for local user management configuration";
+
+        container LOCAL_USER {
+            description "LOCAL_USER part of config_db.json";
+
+            list LOCAL_USER_LIST {
+                key "username";
+                description "List of declaratively managed local users.";
+
+                must "count(../LOCAL_USER_LIST[role='administrator' and (not(enabled) or enabled='true')]) >= 1" {
+                    error-message "At least one administrator user must remain enabled.";
+                }
+
+                leaf username {
+                    type string {
+                        pattern '[a-z_][a-z0-9_-]*[$]?' {
+                            error-message "Invalid username. Must start with a lowercase letter or underscore, followed by lowercase letters, numbers, underscores, or hyphens.";
+                        }
+                        length 1..32;
+                    }
+                    must ". != 'root'" {
+                        error-message "Username cannot be 'root'.";
+                    }
+                    description "The username for the local account.";
+                }
+
+                leaf role {
+                    type user-role;
+                    mandatory true;
+                    description "The role assigned to the user, which determines their group memberships and privileges.";
+                }
+
+                leaf password_hash {
+                    type string;
+                    mandatory true;
+                    must "not(starts-with(., '!'))" {
+                        error-message "Password hash cannot start with '!'. Use the 'enabled' attribute to disable user accounts.";
+                    }
+                    description "The hashed password string for the user, as found in /etc/shadow. Password hashes can be generated using 'mkpasswd' utility or programmatically using libraries like 'passlib'. To disable an account, use the 'enabled' attribute instead of prepending '!' to the password hash.";
+                }
+
+                leaf-list ssh_keys {
+                    type string;
+                    description "A list of full public SSH key strings.";
+                }
+
+                leaf enabled {
+                    type boolean;
+                    default true;
+                    description "Whether the user account is enabled. When false, the password is disabled by prepending '!' to prevent password-based login while preserving SSH key access.";
+                }
+            }
+        }
+
+        container LOCAL_ROLE_SECURITY_POLICY {
+            description "LOCAL_ROLE_SECURITY_POLICY part of config_db.json";
+
+            list LOCAL_ROLE_SECURITY_POLICY_LIST {
+                key "role";
+                description "Global security policies applied to users based on their role.";
+
+                leaf role {
+                    type user-role;
+                    description "The role for which this security policy applies.";
+                }
+
+                leaf max_login_attempts {
+                    type uint32 {
+                        range "1..1000";
+                    }
+                    description "Maximum number of failed login attempts before accounts with this role are locked. If not set, system defaults apply.";
+                }
+            }
+        }
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -147,6 +147,7 @@`
`147`	`147`	`'sonic-smart-switch.yang',`
`148`	`148`	`'sonic-spanning-tree.yang',`
`149`	`149`	`'sonic-srv6.yang',`
	`150`	`+ 'sonic-user.yang',`
`150`	`151`	`]`
`151`	`152`
`152`	`153`	`class my_build_py(build_py):`