user-management: User docs flows updated

Added stacked-pam, phosphor-user-manager & authorization flow

Change-Id: I3d05306ff337c79034f10f5e75c94172d65bb7f4
Signed-off-by: Richard Marian Thomaiyar <richard.marian.thomaiyar@linux.intel.com>

1 files changed, 154 insertions, 23 deletions

diff --git a/user_management.md b/user_management.md
index 6a5fc57..e296448 100644
--- a/user_management.md
+++ b/user_management.md
@@ -80,29 +80,30 @@ for detailed user management D-Bus API and interfaces.
     ||  |PAM for user   | |  |Create new user| |   | Redfish specific 1:1 | ||
     ||  |authentication | |  |or delete or   | |   | user settings storage| ||
     ||  |_|_____________| |  |update________|| |   |**********************| ||
-    ||====|===============|=================|===========^===================||
-          |                                 |           |
-          V   Storage                       |           |
-    |**************|********************|   V           ^              NET-IPMID
-    |  pam_unix -  | pam_ipmi- encrypted|   |           |    ===========================
-    |  /etc/shadow | password (only if  |   |           |    ||                        ||
-    |  (hashed)    | user in ipmi group)|   |           |    || _____________________  ||
-    |***********************|***********|   |           |    || | 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            | ||
+    ||====|===============|=================|===========^===================||            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   | ||
@@ -112,6 +113,45 @@ for detailed user management D-Bus API and interfaces.
 
 ```
 
+## User management - overview
+
+```
+                             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)                        |      |
+          |    +---------------------------------------------+      |
+          |                                                         |
+          +---------------------------------------------------------+
+
+```
+
+
 ## OpenBMC - User Management - User creation from webserver flow - with all groups
 
 ```
@@ -278,6 +318,97 @@ if required                         |                                    |
                                     |                                    |
 --------------------------------------------------------------------------
 ```
+## Authentication flow
+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           |    |
+                |     +-----------------------+    |
+                +----------------------------------+
+```
+## Password update
+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 |  |
+                |  +----------------------------+  |
+                |                                  |
+                +----------------------------------+
+```
+
+## Authorization flow (except IPMI)
+
+```
+                                +
+                                |
+                                |
+                  +-------------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.                     |
+                  +----------------------------+
+
+
+```
+
 
 ## Recommended Implementation
 1. As per IPMI spec the max user list can be 15 (+1 for NULL User). Hence