diff --git a/_images/create_role.png b/_images/create_role.png new file mode 100644 index 00000000000..0914a5829bc Binary files /dev/null and b/_images/create_role.png differ diff --git a/_sources/index.txt b/_sources/index.txt index 44061c60705..044548c17a9 100644 --- a/_sources/index.txt +++ b/_sources/index.txt @@ -32,6 +32,7 @@ Contents installation tutorial + security videos gallery druid diff --git a/_sources/installation.txt b/_sources/installation.txt index 314e1f0eccc..3d895a005f9 100644 --- a/_sources/installation.txt +++ b/_sources/installation.txt @@ -28,7 +28,7 @@ the required dependencies are installed: :: For **Fedora** and **RHEL-derivatives**, the following command will ensure that the required dependencies are installed: :: - + sudo yum upgrade python-setuptools sudo yum install gcc libffi-devel python-devel python-pip python-wheel openssl-devel @@ -88,10 +88,10 @@ To configure your application, you need to create a file (module) of the parameters you can copy / paste in that configuration module: :: #--------------------------------------------------------- - # Caravel specifix config + # Caravel specific config #--------------------------------------------------------- ROW_LIMIT = 5000 - WEBSERVER_THREADS = 8 + CARAVEL_WORKERS = 16 CARAVEL_WEBSERVER_PORT = 8088 #--------------------------------------------------------- @@ -228,6 +228,20 @@ Note that you can run the ``caravel refresh_druid`` command to refresh the metadata from your Druid cluster(s) +CORS +----- + +The extra CORS Dependency must be installed: + + caravel[cors] + + +The following keys in `caravel_config.py` can be specified to configure CORS: + + +* ``ENABLE_CORS``: Must be set to True in order to enable CORS +* ``CORS_OPTIONS``: options passed to Flask-CORS (`documentation `) + Upgrading --------- diff --git a/_sources/security.txt b/_sources/security.txt new file mode 100644 index 00000000000..c0347581184 --- /dev/null +++ b/_sources/security.txt @@ -0,0 +1,92 @@ +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. + + +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 + the checkbox ``Is Restricted`` in the row of the metric ``revenue``. + +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 + click the Save button on the bottom of the page. + +Any users without the permission will see the error message +*Access to the metrics denied: revenue (Status: 500)* in the slices. +It also happens when the user wants to access a post-aggregation metric that +is dependent on revenue. diff --git a/_static/img/create_role.png b/_static/img/create_role.png new file mode 100644 index 00000000000..0914a5829bc Binary files /dev/null and b/_static/img/create_role.png differ diff --git a/druid.html b/druid.html index 1a89ecc262e..8f7cb3afc87 100644 --- a/druid.html +++ b/druid.html @@ -70,6 +70,7 @@ aria-labelledby="dLabelGlobalToc">