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