1# User Management - OpenBMC - Design document 2 3## Scope 4This document covers the architectural, interface, and design details needed for 5user-management components. The implementation detail is beyond the scope of 6this document. 7 8## Basic principles in design 91. Use common user-management (e.g. phosphor-user-manager) rather than 10application-based user-management. Especially, avoid IPMI based user-management. 112. For security reasons, avoid transmitting passwords over any D-Bus API. 12Observe this rule even while creating, modifying or authenticating the user. 133. Have applications use the PAM module to authenticate the user instead of 14relying on a D-Bus API-based approach. 154. User creation has to be generic in nature wherever possible. 165. As IPMI requires clear text password (Refer IPMI 2.0 specification, section 1713.19-13.33 inclusive for more details), new PAM module (e.g. pam-ipmi modules) 18has to be used along with regular PAM password hashing modules (e.g. pam-unix), 19which will store the password in encrypted form. Implementation can elect to 20skip this if the IPMI daemon is not the part of the distribution or if the user 21created doesn't have an 'ipmi' group role. 226. User name, Password, Group and Privilege roles are maintained by the common 23user-management (e.g. phosphor-user-manager), whereas individual user-related 24settings for any application has to be managed by that application. In other 25words, with the exception of User Name, Password, Group and Privileged Role, 26the rest of the settings needed has to be owned by the application in question. 27(e.g. IPMI daemon has to manage settings like channel based restriction etc. 28for the corresponding user). Design is made to cover this scenario. 29 30## Supported Group Roles 31The purpose of group roles is to determine the first-level authorization of the 32corresponding user. This is used to determine at a high level whether the user 33is authorized to the required interface. 34In other words, users should not be allowed to login to SSH if they only belong 35to webserver group and not to group SSH. Also having group roles in common 36user-management (e.g. phosphor-user-manager) allows different application to 37create roles for the other (e.g. Administrative user will be able to create a 38new user through webserver who will be able to login to webserver/REDFISH & 39IPMI etc.) 40 41*Note: Group names are for representation only and can be modified/extended 42 based on the need* 43 44|Sl. No| Group Name | Purpose / Comments | 45|-----:|------------|-----------------------------------| 46|1 | ssh | Users in this group are only allowed to login through SSH.| 47|2 | ipmi | Users in this group are only allowed to use IPMI Interface.| 48|3 | redfish | Users in this group are only allowed to use REDFISH Interface.| 49|4 | web | Users in this group are only allowed to use webserver Interface.| 50 51## Supported Privilege Roles 52OpenBMC supports privilege roles which are common across all the supported 53groups (i.e. User will have same privilege for REDFISH / Webserver / IPMI / 54SSH). User can belong to any one of the following privilege roles at any point 55of time. 56 57*Note: Privileges are for representation only and can be modified/extended 58 based on the need* 59 60|Sl. No| Privilege roles | Purpose / Comments | 61|-----:|-----------------|-----------------------------------| 62|1 | admin | Users are allowed to configure all OpenBMC (including user-management, network and all configurations). Users will have full administrative access.| 63|2 | operator | Users are allowed to view and control basic operations. This includes reboot of the host, etc. But users are not allowed to change other configuration like user, network, etc.| 64|3 | user | Users only have read access and can't change any behavior of the system.| 65|4 | no-access | Users having empty or no privilege will be reported as no-access, from IPMI & REDFISH point of it.| 66 67## Common User Manager - D-Bus API (phosphor-user-manager) 68User Manager service exposes D-Bus methods for user-management operations. 69It exposes `xyz.openbmc_project.User.Manager` as a service and handles 70objects through `org.freedesktop.DBus.ObjectManager`. Please refer 71https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/User 72for detailed user management D-Bus API and interfaces. 73 74## OpenBMC - User Management - High Level architectural diagram 75 76``` 77 WEBSERVER/REDFISH 78 ======================================================================== 79 || ________________ | ________________ | |**********************| || 80 || |PAM for user | | |Create new user| | | Redfish specific 1:1 | || 81 || |authentication | | |or delete or | | | user settings storage| || 82 || |_|_____________| | |update________|| | |**********************| || 83 ||====|===============|=================|===========^===================|| Network 84 | | | ||**********************|| 85 V Storage | |--------------------------|| MaxPrivilege - max || 86 |**************|********************| V ^ || allowed privilege on || 87 | pam_unix - | pam_ipmi- encrypted| | | || channel || 88 | /etc/shadow | password (only if | | | NET-IPMID ************************** 89 | (hashed) or | user in ipmi group)| | | =========================== | 90 | pam_ldap | | | | || _____________________ || | 91 |***********************|***********| | | || | RMCP+ login using | || | 92 +---<-----------------<---------<---- clear text password| || | 93 | | || |____________________| || | 94 | | ||________________________|| | 95 D-Bus Call | | || _____________________ || | 96 +------------+ ^ || | Create new user | || | 97 | | || | or delete or | || | 98 Common user manager | D-Bus Call | || | update | || | 99 ||==========================V==||<---------------------<----|(Note: Host-IPMID | || | 100 || phosphor-user-manager || | || | must use same logic| || | 101 || || | || |____________________| || | 102 ||======================|======|| | || || | 103 V | || |********************| || | 104 | ^ || | IPMI specific 1:1 | || | 105 | | || | user mappings | || | 106 +------>-------------->-----+------>| storage |<--------| 107 PropertiesChanged / || | Note: Either Host | || 108 InterfacesAdded / || | / Net IPMID must | || 109 InterfacesRemoved / || | implement signal | || 110 UserRenamed Signals || | handler | || 111 || |********************| || 112 ||========================|| 113 114``` 115 116## User management - overview 117 118``` 119 user management 120 +---------------------------------------------------------+ 121 | phosphor-user-manager | 122 | +---------------------------------------------+ | 123 | | Local user management: | | 124 | | I: Manager | | 125 | | M: CreateUser, RenameUser | | 126 | | P: AllPrivileges, AllGroups | | 127 | | S: UserRenamed | | 128 | | | | 129 | | I: Attributes | | 130 | | PATH: /xyz/openbmc_project/user/<name> | | 131 | | P: UserGroups, UserPrivilege, UserEnabled, | | 132 | | UserLockedForFailAttempt | | 133 | | | | 134 | | I: AccountPolicy | | 135 | | P: MaxLoginBeforeLockout, MinPasswordLength | | 136 | | AccountUnlockTimeout, RememberOldPassword | | 137 | | | | 138 | | General API (Local/Remote) | | 139 | | M: GetUserInfo() | | 140 | | | | 141 | +---------------------------------------------+ | 142 | | 143 | Remote User Management - Configuration | 144 | +--------------------------+------------------+ | 145 | | Provides interface for remote | | 146 | | user management configuration | | 147 | | (LDAP / NIS / KRB5) | | 148 | +---------------------------------------------+ | 149 | | 150 +---------------------------------------------------------+ 151 152``` 153 154 155## OpenBMC - User Management - User creation from webserver flow - with all groups 156 157``` 158------------------------------------|---------------------------------- -|-----------------------------| 159WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) | 160------------------------------------|------------------------------------|-----------------------------| 1611.Request to add new user | | | 162with 'ipmi, redfish' Group. | | | 163Webserver sends D-Bus command | | | 164to user-manager with User Name, | | | 165Groups and Privilege (No Password) | | | 166 (REQ)---------> | | 167 | 2. Validate inputs, including | | 168 | group restrictions. | | 169 | if successful go to step 4, else | | 170 | return a corresponding error, (e.g.| | 171 | too many users, user name is too | | 172 | long (say, more than IPMI required | | 173 | 16 bytes etc.) | | 174 <-------------(FAILURE) | | 1753. Throw error to the user | | | 176 | | | 177 | 4. Add User Name, Groups and | | 178 | Privileges accordingly. Send signal| | 179 | for User Name created ---(SIGNAL)-> | 180 | (InterfacesAdded) | 5. IPMI & REDFISH can | 181 | | register for 'UserUpdate' | 182 | | signal handler and use | 183 | | the same to maintain 1:1 | 184 | | mapping, if required | 185 <-------------(SUCCESS) | | 1866. User created successfully but | | | 187still can't login, as there is no | | | 188password set. | | | 189 | | | 1907.Set the password for | | | 191the user using pam_chauthtok() | | | 192(which will store clear-text | | | 193password in encrypted form, if | | | 194user is part of 'ipmi' Group) | | | 195 | | | 1968. User created successfully | | | 197-------------------------------------------------------------------------------------------------------- 198``` 199 200## OpenBMC - User Management - User creation from IPMI - 'ipmi' Group only 201 202``` 203------------------------------------|---------------------------------- -|-----------------------------| 204IPMI | Common User Manager | pam_unix/pam_ipmi storage | 205------------------------------------|------------------------------------|-----------------------------| 2061. User sends Set User Name command.| | | 207IPMI Sends D-Bus command to | | | 208to user-manager with User Name | | | 209Groups & privileges (No Password) (REQ)---------> | | 210(Note: Configurations for other | | | 211commands like Set User Access / | | | 212Channel access has to be stored | | | 213in IPMI NV along with User Name) | | | 214 | 2. Validate inputs, including | | 215 | group restrictions. | | 216 | if success go to step 4, else | | 217 | return a corresponding error. | | 218 <-------------(FAILURE) | | 2193. Return error to the Set User | | | 220Name command. User creation failed. | | | 221 | 4. Add User Name, Groups and | | 222 | Privileges accordingly. Send signal| | 223 | for User Name created | | 224 <-------------(SIGNAL) (InterfacesAdded) | | 2255. IPMI can register for | | | 226'UserUpdate' signal handler and use | | | 227the same to maintain 1:1 mapping, | | | 228if required | | | 229 <-------------(SUCCESS) | | 2306. User sends Set User Password | | | 231command. IPMI uses pam-ipmi | | | 232to set the password. | | | 233(Note: can't accept password without| | | 234Set User Name command in first | | | 235place as User Name has to exist | | | 236before trying to store the password.| | | 237Implementation can elect to accept | | | 238the password and set it through PAM | | | 239after Set User Name command) (SET)----------------------------------------> pam-ipmi will store | 240 | |clear text password in | 241 | |encrypted form along with | 242 | |hashed password by pam-unix, | 243 | |when the user belongs to IPMI| 244 <----------------------------------------------(SUCCESS) | 2457. User created successfully | | | 246but will allow only when user is | | | 247enabled. IPMI shouldn't allow user | | | 248to login if user is disabled | | | 249(Note: stored in IPMI NV). | | | 250-------------------------------------------------------------------------------------------------------- 251``` 252 253## OpenBMC - User Management - User deletion from webserver flow - with all groups 254 255``` 256------------------------------------|---------------------------------- -|-----------------------------| 257WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) | 258------------------------------------|------------------------------------|-----------------------------| 2591.Request to delete existing user | | | 260with 'ipmi, redfish' group | | | 261Webserver sends D-Bus command | | | 262to user-manager with User Name | | | 263to be deleted (REQ)---------> | | 264 | 2. Validate inputs, including | | 265 | group restrictions. | | 266 | if successful go to step 4, else | | 267 | return corresponding error. | | 268 | Can be user does not exist etc. | | 269 <-------------(FAILURE) | | 2703. Throw error to the user | | | 271 | | | 272 | 4. Delete User Name, Group and | | 273 | privileges along with password. | | 274 | User Name deleted ---(SIGNAL)-> | 275 | (InterfacesRemoved) | 5. IPMI & REDFISH can | 276 | | register for 'UserUpdate' | 277 | | signal handler and use | 278 | | the same to maintain 1:1 | 279 | | mapping, if required | 280 | | IPMI must delete stored | 281 | | encrypted password. | 282 <-------------(SUCCESS) | | 2836. User deleted successfully, | | | 284 | | | 285-------------------------------------------------------------------------------------------------------- 286``` 287 288## OpenBMC - User Management - User deletion from IPMI - 'ipmi' Group only 289 290``` 291------------------------------------|---------------------------------- -| 292IPMI | Common User Manager | 293------------------------------------|------------------------------------| 2941. User sends Set User Name command | | 295to clear user name. Send D-Bus API | | 296to user-manager with User Name | | 297to delete (REQ)---------> | 298(Note: Configurations for other | | 299commands like Set User Access / | | 300Channel access has to be stored | | 301in IPMI NV along with User Name) | | 302 | 2. Validate inputs, including | 303 | group restrictions. | 304 | if successful go to step 4, else | 305 | return a corresponding error (e.g. | 306 | User name doesn't exists etc.) | 307 <-------------(FAILURE) | 3083. Return error to the Set User | | 309Name command. User deletion failed. | | 310 | | 311 <-------------(SIGNAL) 4. User Name deleted | 3125. IPMI can register for | (InterfacesRemoved) | 313'UserUpdate' signal handler and use | | 314the same to maintain 1:1 mapping, | | 315if required | | 316 <-------------(SUCCESS) | 3176. User deleted successfully | | 318 | | 319-------------------------------------------------------------------------- 320``` 321## Authentication flow 322Applications must use `pam_authenticate()` API to authenticate user. 323Stacked PAM modules are used such that `pam_authenticate()` can be used 324for both local & remote users. 325 326``` 327 +----------------------------------+ 328 | Stacked PAM Authentication | 329 | +-----------------------+ | 330 | | pam_tally2.so | | 331 | | user failed attempt | | 332 | | tracking module. | | 333 | +-----------------------+ | 334 | | 335 | +-----------------------+ | 336 | | pam_unix.so / local | | 337 | | user authentication | | 338 | | module. | | 339 | +-----------------------+ | 340 | | 341 | +-----------------------+ | 342 | | nss_pam_ldap.so / any | | 343 | | remote authentication | | 344 | | pam modules | | 345 | +-----------------------+ | 346 +----------------------------------+ 347``` 348## Password update 349Applications must use `pam_chauthtok()` API to set / change user password. 350Stacked PAM modules allow all 'ipmi' group user passwords to be stored 351in encrypted form, which will be used by IPMI. The same has been performed 352by `pam_ipmicheck` and `pam_ipmisave` modules loaded as first & last modules 353in stacked pam modules. 354 355``` 356 +------------------+---------------+ 357 | Stacked PAM - Password | 358 | | 359 | +----------------------------+ | 360 | | pam_cracklib.so. | | 361 | | Strength checking the | | 362 | | password for acceptance | | 363 | +----------------------------+ | 364 | | 365 | +----------------------------+ | 366 | | pam_ipmicheck.so. Checks | | 367 | | password acceptance for | | 368 | | 'ipmi' group users | | 369 | +----------------------------+ | 370 | | 371 | +----------------------------+ | 372 | | pam_pwhistory.so. Checks | | 373 | | to avoid last used | | 374 | | passwords | | 375 | +----------------------------+ | 376 | | 377 | +-------------+--------------+ | 378 | | pam_unix.so - to update | | 379 | | local user's password | | 380 | | | | 381 | +----------------------------+ | 382 | | 383 | +-----------------+----------+ | 384 | | pam_ipmisave.so - stores | | 385 | | 'ipmi' group user's | | 386 | | password in encrypted form | | 387 | +----------------------------+ | 388 | | 389 +----------------------------------+ 390``` 391 392## Authorization flow (except IPMI) 393 394``` 395 + 396 | 397 | 398 +-------------v--------------+ 399 |pam_authenticate() to | 400 |authenticate the user | 401 |(local / remote) | 402 +-------------+--------------+ 403 | 404 | 405 +-------------v--------------+ 406 |Read user properties using | 407 |GetUserInfo() (for local & | 408 |remote users). | 409 |Allow group access based on | 410 |group property | 411 +-------------+--------------+ 412 | 413 | 414 +-------------v--------------+ 415 |Read Channel MaxPrivilege | 416 |from /xyz/openbmc_project/ | 417 |network/ethX. Use the | 418 |minimum of user & channel | 419 |privilege as the privilege | 420 |Note: Implementation can | 421 |elect to skip the same, if | 422 |authorization based on | 423 |channel restriction is not | 424 |needed. | 425 +----------------------------+ 426 427 428``` 429 430 431## LDAP 432 433SSH, Redfish and Webserver interface allows the user to authenticate against an 434LDAP directory. IPMI interface cannot be used to authenticate against LDAP, 435since IPMI needs the password in clear text at the time of session setup. 436 437In OpenBMC, PAM based authentication is implemented, so for both LDAP users and 438local users, the authentication flow is the same. 439 440For the LDAP user accounts, there is no LDAP attribute type that corresponds to 441the OpenBMC privilege roles. The preferred way is to group LDAP user accounts 442into LDAP groups. D-Bus API is provided for the user to assign privilege role 443to the LDAP group. 444 445## Authorization Flow 446 447This section explains how the privilege roles of the user accounts are 448consumed by the webserver interface. The privilege role is a property of the 449user D-Bus object for the local users. For the LDAP user accounts, the privilege 450role will be based on the LDAP group. The LDAP group to privilege role mapping 451needs to be configured prior to authenticating with the LDAP user accounts. 452 4531. Invoke PAM API for authenticating with user credentials. Proceed, if 454the authentication succeeds. 4552. Check if the user is a local user account. If the user account is local, 456fetch the privilege role from the D-Bus object and update the session 457information. 4583. If the user account is not local, read the group name for the user. 4594. Fetch the privilege role corresponding to the group name, update the session 460information with the privilege role. 4615. If there is no mapping for group name to privilege role, default to `user` 462privilege role for the session. 463 464## Recommended Implementation 4651. As per IPMI spec the max user list can be 15 (+1 for NULL User). Hence 466implementation has to be done in such a way that no more than 15 users are 467getting added to the 'ipmi' Group. Phosphor-user-manager has to enforce this 468limitation. 4692. Should add IPMI_NULL_USER by default and keep the user in disabled state. 470This is to prevent IPMI_NULL_USER from being created as an actual user. This is 471needed as NULL user with NULL password in IPMI can't be added as an entry from 472Unix user-management point of it. 4733. User creation request from IPMI / REDFISH must be handled in 474the same manner as described in the above flow diagram. 4754. Adding / removing a user name from 'ipmi' Group role must force a Password 476change to the user. This is needed as adding to the 'ipmi' Group of existing 477user requires clear text password to be stored in encrypted form. Similarly 478when removing a user from IPMI group, must force the password to be changed 479as part of security measure. 4805. IPMI spec doesn't support groups for the user-management. Hence the 481same can be implemented through OEM Commands, thereby creating a user in 482IPMI with different group roles. 4836. Do no use 'Set User Name' IPMI command to extend already existing 484non-ipmi group users to 'ipmi' group. 'Set User Name' IPMI command will not be 485able to differentiate between new user request or request to extend an existing 486user to 'ipmi' group. Use OEM Commands to extend existing users to 'ipmi' group. 487Note: 'Set User Name' IPMI command will return CCh 'Invalid data field in 488Request' completion code, if tried to add existing user in the system. 489 490## Deployment - Out of factory 491### Guidelines 492As per [SB-327 Information Privacy](https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327), Connected devices must avoid 493shipping with generic user name & password. The reasonable security expected is 4941. Preprogrammed password unique to each device 4952. Forcing user to generate new authentication account, before using the device. 496 497### Generating user during deployment: 498To adhere above mentioned guideline and to make OpenBMC more secure, this design 499specifies about forcing end-user to generate a new account, during deployment 500through any of the system in-band interfaces (like KCS etc.). 501IPMI 2.0 specification provides commands like `SetUserName`, `SetUserPassword`, 502`SetUserAccess`, which must be used to create a new user account instead of 503using any generic default user name and password. Accounts created through this 504method have access to IPMI, REDFISH & Webserver and can be used to create more 505accounts through out-of-band interfaces. 506 507### Special user - root – user id 0: 508Exposing root account (user id 0) to end-user by default (other than debug / 509developer scenario) is security risk. Hence current architecture recommends not 510to enable root user by default for end-user. 511For general login for debug / developer builds, a new default user with password 512can be created by specifying the same in local.conf.sample file. This can be 513used to establish a session by default (CI systems etc. can use this account). 514From OpenBMC package user name `openbmc` with password `0penBmc$` can be added. 515 516#### Debugging use-case 517`root` user / sudo privilege access are required during development / debug 518phase of the program. For this purpose a new IPMI OEM command (TBD) / REDFISH 519OEM action(TBD) to can be used to set password for the root user, after which 520`root` user can be used to login to the serial console and for further debugging 521(Note: `root` user will not be listed as user account in any interfaces like 522IPMI / REDFISH from user management point of view). 523 524### Deployment for systems without in-band interfaces: 525Any systems which doesn’t have in-band system interface can generate passwords 526uniquely for each & every device or can expose a default user name & password 527forcing end-user to update the same, before using the device (TBD). 528