Skip to content

Commit

Permalink
Adding a security section to the docs (#561)
Browse files Browse the repository at this point in the history
  • Loading branch information
mistercrunch committed Jun 3, 2016
1 parent 5bc5021 commit b5fe9db
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 0 deletions.
Binary file added caravel/assets/images/create_role.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Contents

installation
tutorial
security
videos
gallery
druid
Expand Down
70 changes: 70 additions & 0 deletions docs/security.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
Security
========
Security in Caravel is handled by Flask AppBuilder (FAB). FAB is a
"Simple and rapid application development framework, built on top of Flask.".
FAB provides authentication, user management, permissions and roles.


Provided Roles
--------------
Caravel ships with 3 roles that are handled by Caravel itself. You can
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.

Alpha
"""""
Alpha have access to all data sources, but they cannot grant or revoke access
from other users. They are also limited to altering the objects that they
own. Alpha users can add and alter data sources.

Gamma
"""""
Gamma have limited access. They can only consume data coming from data sources
they have been giving access to through another complementary role.
They only have access to view the slices and
dashboards made from data sources that they have access to. Currently Gamma
users are not able to alter or add data sources. We assume that they are
mostly content consumers, though they can create slices and dashboards.

Also note that when Gamma users look at the dashboards and slices list view,
they will only see the objects that they have access to.


Managing Gamma per data source access
-------------------------------------
Here's how to provide users access to only specific datasets. First make
sure the users with limited access have [only] the Gamma role assigned to
them. Second, create a new role (``Menu -> Security -> List Roles``) and
click the ``+`` sign.

.. image:: _static/img/create_role.png
:scale: 50 %

This new window allows you to give this new role a name, attribute it to users
and select the tables in the ``Permissions`` dropdown. To select the data
sources you want to associate with this role, simply click in the dropdown
and use the typeahead to search for your table names.

You can then confirm with your Gamma users that they see the objects
(dashboards and slices) associated with the tables related to their roles.


Customizing
-----------

The permissions exposed by FAB are very granular and allow for a great level
of customization. FAB creates many permissions automagically for each model
that is create (can_add, can_delete, can_show, can_edit, ...) as well as for
each view. On top of that, Caravel can expose more granular permissions like
``all_datasource_access``.

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.

0 comments on commit b5fe9db

Please sign in to comment.