doc/mgr/dashboard: user and role management documentation

Signed-off-by: Ricardo Dias <rdias@suse.com>

diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst
index bba14ed867e484ef231e15c8375bbd20f64dcc94..fed3a920cd50907a573044fd3038cbd10c203aab 100644 (file)
--- a/doc/mgr/dashboard.rst
+++ b/doc/mgr/dashboard.rst
@@ -40,7 +40,8 @@ information and statistics about the Ceph cluster using a web server hosted by
 The dashboard currently provides the following features to monitor and manage
 various aspects of your Ceph cluster:
 
-* **Username/password protection**: The dashboard can only be accessed by
+* **Multi-User and Role Management**: The dashboard supports the management of
+  multiple user accounts, and the management of permission roles.
   providing a configurable username and password.
 * **SSL/TLS support**: All HTTP communication between the web browser and the
   dashboard is secured via SSL. A self-signed certificate can be created with
@@ -181,13 +182,16 @@ app.
 Username and password
 ^^^^^^^^^^^^^^^^^^^^^
 
-In order to be able to log in, you need to define a username and password, which
-will be stored in the MON's configuration database::
+In order to be able to log in, you need to create a user account and associate
+it with at least one role. We provide a set of predefined *system roles* that
+you can use. For more details please refer to the `User and Role Management`_
+section.
 
-  $ ceph dashboard set-login-credentials <username> <password>
+To create a user with the administrator role you can use the following
+commands::
+
+  $ ceph dashboard ac-user-create <username> <password> administrator
 
-The password will be stored in the configuration database in encrypted form
-using ``bcrypt``. This is a global setting that applies to all dashboard instances.
 
 Enabling the Object Gateway management frontend
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -316,6 +320,173 @@ previously defined username and password. Select the **Keep me logged in**
 checkbox if you want to skip the username/password request when accessing the
 dashboard in the future.
 
+
+User and Role Management
+------------------------
+
+User Accounts
+^^^^^^^^^^^^^
+
+Ceph Dashboard supports managing multiple user accounts. Each user account
+consists of a username, a password (stored in encrypted form using ``bcrypt``),
+an optional name, and an optional email address.
+
+User accounts are stored in MON's configuration database, and are globally
+shared across all ceph-mgr instances.
+
+We provide a set of CLI commands to manage user accounts:
+
+- *Show User(s)*::
+
+  $ ceph dashboard ac-user-show [<username>]
+
+- *Create User*::
+
+  $ ceph dashboard ac-user-create <username> <password> [<rolename>] [<name>] [<email>]
+
+- *Delete User*::
+
+  $ ceph dashboard ac-user-delete <username>
+
+- *Change Password*::
+
+  $ ceph dashboard ac-user-set-password <username> <password>
+
+- *Modify User (name, and email)*::
+
+  $ ceph dashboard ac-user-set-info <username> <name> <email>
+
+
+User Roles and Permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+User accounts are also associated with a set of roles that define which
+dashboard fuctionality can be accessed by the user.
+
+Dashboard functionality/modules are grouped within a *security scope*.
+Security scopes are predefined and static. The current avaliable security
+scopes are:
+
+- **hosts**: includes all features related to the ``Hosts`` menu
+  entry.
+- **config-opt**: includes all features related to management of Ceph
+  configuration options.
+- **pool**: includes all features related to pool management.
+- **osd**: includes all features related to OSD management.
+- **monitor**: includes all features related to Monitor management.
+- **rbd-image**: includes all features related to RBD image
+  management.
+- **rbd-mirroring**: includes all features related to RBD-Mirroring
+  management.
+- **iscsi**: includes all features related to iSCSI management.
+- **rgw**: includes all features related to Rados Gateway management.
+- **cephfs**: includes all features related to CephFS management.
+- **manager**: include all features related to Ceph Manager
+  management.
+- **log**: include all features related to Ceph logs management.
+- **grafana**: include all features related to Grafana proxy.
+
+A *role* specifies a set of mappings between a *security scope* and a set of
+*permissions*. There are four types of permissions:
+
+- **read**
+- **create**
+- **update**
+- **delete**
+
+See below for an example of a role specification based on a Python dictionary::
+
+  # example of a role
+  {
+    'role': 'my_new_role',
+    'description': 'My new role',
+    'scopes_permissions': {
+      'pool': ['read', 'create'],
+      'rbd-image': ['read', 'create', 'update', 'delete']
+    }
+  }
+
+The above role dictates that a user has *read* and *create* permissions for
+features related to pool management, and has full permissions for
+features related to RBD image management.
+
+The Dashboard already provides a set of predefined roles that we call
+*system roles*, and can be used right away in a fresh Ceph Dashboard
+installation.
+
+The list of system roles are:
+
+- **administrator**: provides full permissions for all security scopes.
+- **read-only**: provides *read* permission for all security scopes.
+- **block-manager**: provides full permissions for *rbd-image*,
+  *rbd-mirroring*, and *iscsi* scopes.
+- **rgw-manager**: provides full permissions for the *rgw* scope
+- **cluster-manager**: provides full permissions for the *hosts*, *osd*,
+  *monitor*, *manager*, and *config-opt* scopes.
+- **pool-manager**: provides full permissions for the *pool* scope.
+- **cephfs-manager**: provides full permissions for the *cephfs* scope.
+
+The list of currently available roles can be retrieved by the following
+command::
+
+  $ ceph dashboard ac-role-show [<rolename>]
+
+It is also possible to create new roles using CLI commands. The available
+commands to manage roles are the following:
+
+- *Create Role*::
+
+  $ ceph dashboard ac-role-create <rolename> [<description>]
+
+- *Delete Role*::
+
+  $ ceph dashboard ac-role-delete <rolename>
+
+- *Add Scope Permissions to Role*::
+
+  $ ceph dashboard ac-role-add-scope-perms <rolename> <scopename> <permission> [<permission>...]
+
+- *Delete Scope Permission from Role*::
+
+  $ ceph dashboard ac-role-del-perms <rolename> <scopename>
+
+To associate roles to users, the following CLI commands are available:
+
+- *Set User Roles*::
+
+  $ ceph dashboard ac-user-set-roles <username> <rolename> [<rolename>...]
+
+- *Add Roles To User*::
+
+  $ ceph dashboard ac-user-add-roles <username> <rolename> [<rolename>...]
+
+- *Delete Roles from User*::
+
+  $ ceph dashboard ac-user-del-roles <username> <rolename> [<rolename>...]
+
+
+Example of user and custom role creation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this section we show a full example of the commands that need to be used
+in order to create a user account, that should be able to manage RBD images,
+view and create Ceph pools, and have read-only access to any other scopes.
+
+1. *Create the user*::
+
+   $ ceph dashboard ac-user-create bob mypassword
+
+2. *Create role and specify scope permissions*::
+
+   $ ceph dashboard ac-role-create rbd/pool-manager
+   $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager rbd-image read create update delete
+   $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager pool read create
+
+3. *Associate roles to user*::
+
+   $ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only
+
+
 Reverse proxies
 ---------------
 
@@ -329,3 +500,4 @@ to use hyperlinks that include your prefix, you can set the
   ceph config set mgr mgr/dashboard/url_prefix $PREFIX
 
 so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``.
+