Improving the docs around managing roles (#1183)

docs/security.rst

@@ -12,8 +12,8 @@ assume that these 3 roles will stay up-to-date as Caravel evolves.
 
 Admin
 """""
-Admins have all rights, including granting or revoking rights from other
-users and altering other people's slices and dashboards.
+Admins have all possible rights, including granting or revoking rights from
+other users and altering other people's slices and dashboards.
 
 Alpha
 """""
@@ -66,24 +66,65 @@ We do not recommend altering the 3 base roles as there
 are a set of assumptions that Caravel build upon. It is possible though for
 you to create your own roles, and union them to existing ones.
 
-The best way to go is probably to give user ``Gamma`` plus another role
-that would add specific permissions needed by this type of users. 
+Permissions
+"""""""""""
+
+Roles are composed of a set of permissions, and Caravel has many categories
+of permissions. Here are the different categories of permissions:
+
+- **Model & action**: models are entities like ``Dashboard``,
+  ``Slice``, or ``User``. Each model has a fixed set of permissions, like
+  ``can_edit``, ``can_show``, ``can_delete``, ``can_list``, ``can_add``, and
+  so on. By adding ``can_delete on Dashboard`` to a role, and granting that
+  role to a user, this user will be able to delete dashboards.
+- **Views**: views are individual web pages, like the ``explore`` view or the
+  ``SQL Lab`` view. When granted to a user, he/she will see that view in
+  the its menu items, and be able to load that page.
+- **Data source**: For each data source, a permission is created. If the user
+  does not have the ``all_datasource_access`` permission granted, the user
+  will only be able to see Slices or explore the data sources that are granted
+  to them
+- **Database**: Granting access to a database allows for the user to access
+  all data sources within that database, and will enable the user to query
+  that database in SQL Lab, provided that the SQL Lab specific permission
+  have been granted to the user
+
+
+Restricting access to a subset of data sources
+""""""""""""""""""""""""""""""""""""""""""""""
+
+The best way to go is probably to give user ``Gamma`` plus one or many other
+roles that would add access to specific data sources. We recommend that you
+create individual roles for each access profile. Say people in your finance
+department might have access to a set of databases and data sources, and
+these permissions can be consolidated in a single role. Users with this
+profile then need to be attributed ``Gamma`` as a foundation to the models
+and views they can access, and that ``Finance`` role that is a collection
+of permissions to data objects.
+
+One user can have many roles, so a finance executive could be granted
+``Gamma``, ``Finance``, and perhaps another ``Executive`` role that gather
+a set of data sources that power dashboards only made available to executives.
+When looking at its dashboard list, this user will only see the
+list of dashboards it has access to, based on the roles and
+permissions that were attributed.
+
+
+Restricting the access to some metrics
+""""""""""""""""""""""""""""""""""""""
 
-
-Restricting the access to the metrics
--------------------------------------
 Sometimes some metrics are relatively sensitive (e.g. revenue).
 We may want to restrict those metrics to only a few roles.
 For example, assumed there is a metric ``[cluster1].[datasource1].[revenue]``
 and only Admin users are allowed to see it. Here’s how to restrict the access.
 
-1. Edit the datasource (``Menu -> Source -> Druid datasources -> edit the 
-   record "datasource1"``) and go to the tab ``List Druid Metric``. Check 
+1. Edit the datasource (``Menu -> Source -> Druid datasources -> edit the
+   record "datasource1"``) and go to the tab ``List Druid Metric``. Check
    the checkbox ``Is Restricted`` in the row of the metric ``revenue``.
 
-2. Edit the role (``Menu -> Security -> List Roles -> edit the record 
+2. Edit the role (``Menu -> Security -> List Roles -> edit the record
    “Admin”``), in the permissions field, type-and-search the permission
-   ``metric access on [cluster1].[datasource1].[revenue] (id: 1)``, then 
+   ``metric access on [cluster1].[datasource1].[revenue] (id: 1)``, then
    click the Save button on the bottom of the page.
 
 Any users without the permission will see the error message