This document covers the architectural, interface, and design details needed for user-management components. The implementation detail is beyond the scope of this document.
The purpose of group roles is to determine the first-level authorization of the corresponding user. This is used to determine at a high level whether the user is authorized to the required interface. In other words, users should not be allowed to login to SSH if they only belong to webserver group and not to group SSH. Also having group roles in common user-management (e.g. phosphor-user-manager) allows different application to create roles for the other (e.g. Administrative user will be able to create a new user through webserver who will be able to login to webserver/REDFISH & IPMI etc.)
Note: Group names are for representation only and can be modified/extended based on the need
| Sl. No | Group Name | Purpose / Comments |
|---|---|---|
| 1 | ssh | Users in this group are only allowed to login through SSH. |
| 2 | ipmi | Users in this group are only allowed to use IPMI Interface. |
| 3 | redfish | Users in this group are only allowed to use REDFISH Interface. |
| 4 | web | Users in this group are only allowed to use webserver Interface. |
OpenBMC supports privilege roles which are common across all the supported groups (i.e. User will have same privilege for REDFISH / Webserver / IPMI / SSH). User can belong to any one of the following privilege roles at any point of time.
Note: Privileges are for representation only and can be modified/extended based on the need
| Sl. No | Privilege roles | Purpose / Comments |
|---|---|---|
| 1 | admin | Users are allowed to configure all OpenBMC (including user-management, network and all configurations). Users will have full administrative access. |
| 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. |
| 3 | user | Users only have read access and can't change any behavior of the system. |
| 4 | callback | Lowest privilege level, only allowed to initiate IPMI 2.0 specific callbacks. |
User Manager service exposes D-Bus methods for user-management operations. It exposes xyz.openbmc_project.User.Manager as a service and handles objects through org.freedesktop.DBus.ObjectManager. Please refer https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/User for detailed user management D-Bus API and interfaces.
WEBSERVER/REDFISH
========================================================================
|| ________________ | ________________ | |**********************| ||
|| |PAM for user | | |Create new user| | | Redfish specific 1:1 | ||
|| |authentication | | |or delete or | | | user settings storage| ||
|| |_|_____________| | |update________|| | |**********************| ||
||====|===============|=================|===========^===================|| Network
| | | ||**********************||
V Storage | |--------------------------|| MaxPrivilege - max ||
|**************|********************| V ^ || allowed privilege on ||
| pam_unix - | pam_ipmi- encrypted| | | || channel ||
| /etc/shadow | password (only if | | | NET-IPMID **************************
| (hashed) or | user in ipmi group)| | | =========================== |
| pam_ldap | | | | || _____________________ || |
|***********************|***********| | | || | RMCP+ login using | || |
+---<-----------------<---------<---- clear text password| || |
| | || |____________________| || |
| | ||________________________|| |
D-Bus Call | | || _____________________ || |
+------------+ ^ || | Create new user | || |
| | || | or delete or | || |
Common user manager | D-Bus Call | || | update | || |
||==========================V==||<---------------------<----|(Note: Host-IPMID | || |
|| phosphor-user-manager || | || | must use same logic| || |
|| || | || |____________________| || |
||======================|======|| | || || |
V | || |********************| || |
| ^ || | IPMI specific 1:1 | || |
| | || | user mappings | || |
+------>-------------->-----+------>| storage |<--------|
PropertiesChanged / || | Note: Either Host | ||
InterfacesAdded / || | / Net IPMID must | ||
InterfacesRemoved / || | implement signal | ||
UserRenamed Signals || | handler | ||
|| |********************| ||
||========================||
user management
+---------------------------------------------------------+
| phosphor-user-manager |
| +---------------------------------------------+ |
| | Local user management: | |
| | I: Manager | |
| | M: CreateUser, RenameUser | |
| | P: AllPrivileges, AllGroups | |
| | S: UserRenamed | |
| | | |
| | I: Attributes | |
| | PATH: /xyz/openbmc_project/user/<name> | |
| | P: UserGroups, UserPrivilege, UserEnabled, | |
| | UserLockedForFailAttempt | |
| | | |
| | I: AccountPolicy | |
| | P: MaxLoginBeforeLockout, MinPasswordLength | |
| | AccountUnlockTimeout, RememberOldPassword | |
| | | |
| | General API (Local/Remote) | |
| | M: GetUserInfo() | |
| | | |
| +---------------------------------------------+ |
| |
| Remote User Management - Configuration |
| +--------------------------+------------------+ |
| | Provides interface for remote | |
| | user management configuration | |
| | (LDAP / NIS / KRB5) | |
| +---------------------------------------------+ |
| |
+---------------------------------------------------------+
------------------------------------|---------------------------------- -|-----------------------------|
WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) |
------------------------------------|------------------------------------|-----------------------------|
1.Request to add new user | | |
with 'ipmi, redfish' Group. | | |
Webserver sends D-Bus command | | |
to user-manager with User Name, | | |
Groups and Privilege (No Password) | | |
(REQ)---------> | |
| 2. Validate inputs, including | |
| group restrictions. | |
| if successful go to step 4, else | |
| return a corresponding error, (e.g.| |
| too many users, user name is too | |
| long (say, more than IPMI required | |
| 16 bytes etc.) | |
<-------------(FAILURE) | |
3. Throw error to the user | | |
| | |
| 4. Add User Name, Groups and | |
| Privileges accordingly. Send signal| |
| for User Name created ---(SIGNAL)-> |
| (InterfacesAdded) | 5. IPMI & REDFISH can |
| | register for 'UserUpdate' |
| | signal handler and use |
| | the same to maintain 1:1 |
| | mapping, if required |
<-------------(SUCCESS) | |
6. User created successfully but | | |
still can't login, as there is no | | |
password set. | | |
| | |
7.Set the password for | | |
the user using pam_chauthtok() | | |
(which will store clear-text | | |
password in encrypted form, if | | |
user is part of 'ipmi' Group) | | |
| | |
8. User created successfully | | |
--------------------------------------------------------------------------------------------------------
------------------------------------|---------------------------------- -|-----------------------------|
IPMI | Common User Manager | pam_unix/pam_ipmi storage |
------------------------------------|------------------------------------|-----------------------------|
1. User sends Set User Name command.| | |
IPMI Sends D-Bus command to | | |
to user-manager with User Name | | |
Groups & privileges (No Password) (REQ)---------> | |
(Note: Configurations for other | | |
commands like Set User Access / | | |
Channel access has to be stored | | |
in IPMI NV along with User Name) | | |
| 2. Validate inputs, including | |
| group restrictions. | |
| if success go to step 4, else | |
| return a corresponding error. | |
<-------------(FAILURE) | |
3. Return error to the Set User | | |
Name command. User creation failed. | | |
| 4. Add User Name, Groups and | |
| Privileges accordingly. Send signal| |
| for User Name created | |
<-------------(SIGNAL) (InterfacesAdded) | |
5. IPMI can register for | | |
'UserUpdate' signal handler and use | | |
the same to maintain 1:1 mapping, | | |
if required | | |
<-------------(SUCCESS) | |
6. User sends Set User Password | | |
command. IPMI uses pam-ipmi | | |
to set the password. | | |
(Note: can't accept password without| | |
Set User Name command in first | | |
place as User Name has to exist | | |
before trying to store the password.| | |
Implementation can elect to accept | | |
the password and set it through PAM | | |
after Set User Name command) (SET)----------------------------------------> pam-ipmi will store |
| |clear text password in |
| |encrypted form along with |
| |hashed password by pam-unix, |
| |when the user belongs to IPMI|
<----------------------------------------------(SUCCESS) |
7. User created successfully | | |
but will allow only when user is | | |
enabled. IPMI shouldn't allow user | | |
to login if user is disabled | | |
(Note: stored in IPMI NV). | | |
--------------------------------------------------------------------------------------------------------
------------------------------------|---------------------------------- -|-----------------------------|
WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) |
------------------------------------|------------------------------------|-----------------------------|
1.Request to delete existing user | | |
with 'ipmi, redfish' group | | |
Webserver sends D-Bus command | | |
to user-manager with User Name | | |
to be deleted (REQ)---------> | |
| 2. Validate inputs, including | |
| group restrictions. | |
| if successful go to step 4, else | |
| return corresponding error. | |
| Can be user does not exist etc. | |
<-------------(FAILURE) | |
3. Throw error to the user | | |
| | |
| 4. Delete User Name, Group and | |
| privileges along with password. | |
| User Name deleted ---(SIGNAL)-> |
| (InterfacesRemoved) | 5. IPMI & REDFISH can |
| | register for 'UserUpdate' |
| | signal handler and use |
| | the same to maintain 1:1 |
| | mapping, if required |
| | IPMI must delete stored |
| | encrypted password. |
<-------------(SUCCESS) | |
6. User deleted successfully, | | |
| | |
--------------------------------------------------------------------------------------------------------
------------------------------------|---------------------------------- -|
IPMI | Common User Manager |
------------------------------------|------------------------------------|
1. User sends Set User Name command | |
to clear user name. Send D-Bus API | |
to user-manager with User Name | |
to delete (REQ)---------> |
(Note: Configurations for other | |
commands like Set User Access / | |
Channel access has to be stored | |
in IPMI NV along with User Name) | |
| 2. Validate inputs, including |
| group restrictions. |
| if successful go to step 4, else |
| return a corresponding error (e.g. |
| User name doesn't exists etc.) |
<-------------(FAILURE) |
3. Return error to the Set User | |
Name command. User deletion failed. | |
| |
<-------------(SIGNAL) 4. User Name deleted |
5. IPMI can register for | (InterfacesRemoved) |
'UserUpdate' signal handler and use | |
the same to maintain 1:1 mapping, | |
if required | |
<-------------(SUCCESS) |
6. User deleted successfully | |
| |
--------------------------------------------------------------------------
Applications must use pam_authenticate() API to authenticate user. Stacked PAM modules are used such that pam_authenticate() can be used for both local & remote users.
+----------------------------------+
| Stacked PAM Authentication |
| +-----------------------+ |
| | pam_unix.so / local | |
| | user authentication | |
| | module. | |
| +-----------------------+ |
| ... |
| +-----------------------+ |
| | nss_pam_ldap.so / any | |
| | remote authentication | |
| | pam modules | |
| +-----------------------+ |
+----------------------------------+
Applications must use pam_chauthtok() API to set / change user password. Stacked PAM modules allow all 'ipmi' group user passwords to be stored in encrypted form, which will be used by IPMI. The same has been performed by pam_ipmicheck and pam_ipmisave modules loaded as first & last modules in stacked pam modules.
+------------------+---------------+
| Stacked PAM - Password |
| |
| +----------------------------+ |
| | pam_ipmicheck.so. Checks | |
| | password acceptance for | |
| | 'ipmi' group users | |
| +----------------------------+ |
| |
| +-------------+--------------+ |
| | pam_unix.so - to update | |
| | local user's password | |
| | | |
| +----------------------------+ |
| |
| +-----------------+----------+ |
| | pam_ipmisave.so - stores | |
| | 'ipmi' group user's | |
| | password in encrypted form | |
| +----------------------------+ |
| |
+----------------------------------+
+
|
|
+-------------v--------------+
|pam_authenticate() to |
|authenticate the user |
|(local / remote) |
+-------------+--------------+
|
|
+-------------v--------------+
|Read user properties using |
|GetUserInfo() (for local & |
|remote users). |
|Allow group access based on |
|group property |
+-------------+--------------+
|
|
+-------------v--------------+
|Read Channel MaxPrivilege |
|from /xyz/openbmc_project/ |
|network/ethX. Use the |
|minimum of user & channel |
|privilege as the privilege |
|Note: Implementation can |
|elect to skip the same, if |
|authorization based on |
|channel restriction is not |
|needed. |
+----------------------------+