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