docs/designs/redfish-authorization.md

1 # Dynamic Redfish Authorization
9 The Redfish authorization subsystem controls which authenticated users have
13 enhance the current implementation in BMCWeb Redfish interface so that OpenBMC
15 Redfish service restart.
19 ### Redfish Authorization Model
21 The Redfish authorization model consists of the privilege model and the
24 In the privilege model, there are fixed set of standard Redfish roles and each
33 authenticated Redfish role are sufficient to complete the operation in the
34 request. The Redfish Forum provides a Privilege Registry definition in its
47 **Note**, in the Redfish spec, OEM roles can be added via POST to the
64 user groups (SSH, IPMI, Redfish, Web) and a hardcoded list of privileges
82 BMCWeb is an OpenBMC Daemon which implements the Redfish service (it implements
83 other management interfaces as well besides Redfish).
95 convert the privileges to Redfish roles. The hardcoded map is listed below:
97 | Phosphor-user-manager privileges (implemented as groups) | BMCWeb Redfish Roles |
104 To map Redfish role to their assigned Redfish privileges, BMCWeb implements the
107 | BMCWeb Redfish Roles | Assigned Redfish Privileges                                               …
115 Redfish Privileges. An authorization action is performed when a BMCWeb route
116 callback is performed: check if the assigned Redfish Privileges is a superset of
117 the required Redfish Privileges.
130 As mentioned above, majority of the current Redfish authorization settings are
134 2. the mapping from Phosphor-user-manager privileges to Redfish roles
135 3. the set of Redfish roles
136 4. the mapping from Redfish roles to Redfish Privileges
139 However, modern systems have use cases where Redfish roles, Redfish privileges,
143 proper Redfish role and is authorized to access certain resources without
146 Another gap is that current Redfish roles and operation-to-privilege mapping
156 has at least ConfigureComponents Redfish privilege, which leads to being able to
161 BMC implements a dynamic Redfish authorization system:
163 1. Clients shall be able to add new OEM Redfish privileges without recompile
164 2. Clients shall be able to add new OEM Redfish roles and assign it with any
165    existing Redfish privileges without recompile
173    - It rejects deletion of OEM Redfish roles if any user (either local or
175    - It rejects deletion of OEM Redfish privileges if any OEM Redfish role is
179    is not introduced, including non-Redfish routes (e.g., KVM websocket)
180 8. Default OEM roles and Redfish privileges must be selectable on a per system
181    basis at compile time; default Redfish PrivilegeRegistry must be settable on
191     - It shall implement all overrides in the Redfish base Privilege registries
199 11. New Redfish resource can be implemented without modifying custom
205 ### Mapping: Users, Redfish Roles, and Redfish Privileges
207 As mentioned in the background section, existing Redfish roles are stored as
210 representing that a user is a specific Redfish role. BMCWeb then uses a
211 hardcoded table to map Redfish role to Redfish privileges.
214 well with OEM Redfish Roles where a Redfish role maps to a dynamic set of OEM
219 **Store Redfish Roles As Linux Users and Secondary Groups** We propose to store
220 Redfish Roles as both Linux users and secondary groups. Storing as secondary
221 groups is to associate users with Redfish roles. On the other hand, storing as
222 users is to associate Redfish roles with Redfish privileges. See below section
225 Users for Redfish roles won't be any predefined groups (web, redfish, ipmi). We
227 Users for Redfish roles won't have SSH permission as well.
229 Redfish roles will have a fixed prefix "openbmc-rfr-". "rfr" refers to Redfish
231 Redfish role. For example, the base Redfish role "Administrator" will result in
237 **Store Redfish Privileges as Secondary Groups** Redfish privileges will be
239 to Redfish privilege. OEM privileges will have fixed prefix "openbmc-orfp".
240 "orfr" refers to OEM Redfish privilege.
242 **Username to Redfish Role Mapping** Mapping a username to Redfish role becomes
245 **Redfish Role to Redfish Privileges Mapping** Mapping a Redfish Role to Redfish
251 group meaning its Redfish role is "openbmc-orfr-power"; local user
253 "openbmc-orfp-power" groups meaning "openbmc-orfr-power" is assigned to Redfish
289 to base Redfish roles or OEM Redfish roles via RemoteRoleMapping: an LDAP group
290 maps to a single Redfish role stored as local users.
298 in both `priv-user` and `openbmc-orfp-power` will have the following Redfish
301 ### Creation/Deletion: Users, Redfish Roles, and Redfish Privileges
305 #### OEM Redfish Privileges
312 1. Phosphor-user-manager provides DBus APIs to create/delete OEM Redfish
314    how base Redfish roles are stored
315 2. Phosphor-user-manager keeps a maximum number of Redfish privileges; we
318    - Names of OEM Redfish privileges are unique and valid; e.g., start with
321      Redfish roles that have a user associated with)
326 #### OEM Redfish Roles
337 1. Phosphor-user-manager provides DBus APIs to create Redfish role
338 2. Phosphor-user-manager keeps a maximum number of Redfish roles; we propose 32
341    - Names of OEM Redfish roles are unique and valid; e.g., start with
349 assigned Redfish role.
360 Redfish role which is assigned a new set of OEM Redfish Privileges is mapped out
396 ### Non-Redfish Routes or OEM Resources
398 We still keep the current `privileges` C++ API to add explicit Redfish
401 ### Redfish Routes
421 Any Redfish route must provide these attributes. Non Redfish route shall not
426 See below for how we propose to get required Redfish privileges for a given
440 The operation to check if a user is authorized to perform a Redfish operation is
535 Though the Redfish spec declares PrivilegeRegistry to be read-only, this design
572 OEM Redfish roles, Redfish privileges, and users are persisted by Linux. With a
622 1. verify base Redfish roles, privileges, and base operation-to-privilege
623    respect the Redfish spec when no runtime modification is made
624 2. verify Redfish OemPrivilege can be added via PATCH to PrivilegeRegistry and
626 3. verify Redfish OemRole can be added via POST to ManagerAccountCollection with