From 59fc5a6184d47c359fd830fd1a9bded531e3594c Mon Sep 17 00:00:00 2001 From: Multazim Deshmukh <57723564+mdeshmu@users.noreply.github.com> Date: Fri, 13 Oct 2023 20:48:08 +0530 Subject: [PATCH] docs: BugHerd Tasks 88, 89, 90, 91 (#25567) Co-authored-by: Sam Firke --- .../installation/configuring-superset.mdx | 47 ++++++++++++++++++- .../installing-superset-from-scratch.mdx | 6 ++- docs/docs/security/security.mdx | 16 +++++-- 3 files changed, 62 insertions(+), 7 deletions(-) diff --git a/docs/docs/installation/configuring-superset.mdx b/docs/docs/installation/configuring-superset.mdx index e970cdc4224fb..01e6274bbb28f 100644 --- a/docs/docs/installation/configuring-superset.mdx +++ b/docs/docs/installation/configuring-superset.mdx @@ -9,8 +9,22 @@ version: 1 ### Configuration -To configure your application, you need to create a file `superset_config.py` and add it to your -`PYTHONPATH`. If your application was installed using docker compose an alternative configuration is required. See [https://github.com/apache/superset/tree/master/docker#readme](https://github.com/apache/superset/tree/master/docker#readme) for details. +To configure your application, you need to create a file `superset_config.py`. Add this file to your + +`PYTHONPATH` or create an environment variable `SUPERSET_CONFIG_PATH` specifying the full path of the `superset_config.py`. + +For example, if deploying on Superset directly on a Linux-based system where your `superset_config.py` is under `/app` directory, you can run: +```bash +export SUPERSET_CONFIG_PATH=/app/superset_config.py +``` + +If you are using your own custom Dockerfile with official Superset image as base image, then you can add your overrides as shown below: +```bash +COPY --chown=superset superset_config.py /app/ +ENV SUPERSET_CONFIG_PATH /app/superset_config.py +``` + +Docker compose deployments handle application configuration differently. See [https://github.com/apache/superset/tree/master/docker#readme](https://github.com/apache/superset/tree/master/docker#readme) for details. The following is an example of just a few of the parameters you can set in your `superset_config.py` file: ``` @@ -278,6 +292,35 @@ To use LDAP you must install the [python-ldap](https://www.python-ldap.org/en/la See [FAB's LDAP documentation](https://flask-appbuilder.readthedocs.io/en/latest/security.html#authentication-ldap) for details. +### Mapping LDAP or OAUTH groups to Superset roles + +AUTH_ROLES_MAPPING in Flask-AppBuilder is a dictionary that maps from LDAP/OAUTH group names to FAB roles. +It is used to assign roles to users who authenticate using LDAP or OAuth. + +#### Mapping OAUTH groups to Superset roles + +The following AUTH_ROLES_MAPPING dictionary would map the OAUTH group "superset_users" to the Superset roles "Gamma" as well as "Alpha", and the OAUTH group "superset_admins" to the Superset role "Admin". + +AUTH_ROLES_MAPPING = { +"superset_users": ["Gamma","Alpha"], +"superset_admins": ["Admin"], +} + +#### Mapping LDAP groups to Superset roles + +The following AUTH_ROLES_MAPPING dictionary would map the LDAP DN "cn=superset_users,ou=groups,dc=example,dc=com" to the Superset roles "Gamma" as well as "Alpha", and the LDAP DN "cn=superset_admins,ou=groups,dc=example,dc=com" to the Superset role "Admin". + +AUTH_ROLES_MAPPING = { +"cn=superset_users,ou=groups,dc=example,dc=com": ["Gamma","Alpha"], +"cn=superset_admins,ou=groups,dc=example,dc=com": ["Admin"], +} + +Note: This requires AUTH_LDAP_SEARCH to be set. For more details, Please refer (FAB Security documentation)[https://flask-appbuilder.readthedocs.io/en/latest/security.html]. + +#### Syncing roles at login + +You can also use the AUTH_ROLES_SYNC_AT_LOGIN configuration variable to control how often Flask-AppBuilder syncs the user's roles with the LDAP/OAUTH groups. If AUTH_ROLES_SYNC_AT_LOGIN is set to True, Flask-AppBuilder will sync the user's roles each time they log in. If AUTH_ROLES_SYNC_AT_LOGIN is set to False, Flask-AppBuilder will only sync the user's roles when they first register. + ### Flask app Configuration Hook `FLASK_APP_MUTATOR` is a configuration function that can be provided in your environment, receives diff --git a/docs/docs/installation/installing-superset-from-scratch.mdx b/docs/docs/installation/installing-superset-from-scratch.mdx index 8a58c59964a7e..3ba9d34fc768e 100644 --- a/docs/docs/installation/installing-superset-from-scratch.mdx +++ b/docs/docs/installation/installing-superset-from-scratch.mdx @@ -64,7 +64,11 @@ We don't recommend using the system installed Python. Instead, first install the brew install readline pkg-config libffi openssl mysql postgresql@14 ``` -You should install a recent version of Python (the official docker image uses 3.8.16). We'd recommend using a Python version manager like [pyenv](https://github.com/pyenv/pyenv) (and also [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)). +You should install a recent version of Python. Refer to the (setup.py file)[https://github.com/apache/superset/blob/master/setup.py] for a list of Python versions officially supported by Superset. We'd recommend using a Python version manager like [pyenv](https://github.com/pyenv/pyenv) (and also [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)). + +:::tip +To identify the Python version used by the official docker image, see the [Dockerfile](https://github.com/apache/superset/blob/master/Dockerfile). Additional docker images published for newer versions of Python can be found in [this file](https://github.com/apache/superset/blob/master/.github/workflows/docker_build_push.sh). +::: Let's also make sure we have the latest version of `pip` and `setuptools`: diff --git a/docs/docs/security/security.mdx b/docs/docs/security/security.mdx index 5934af51df006..45b603f2a7574 100644 --- a/docs/docs/security/security.mdx +++ b/docs/docs/security/security.mdx @@ -1,11 +1,9 @@ --- -title: Role based Access +title: Security hide_title: true sidebar_position: 1 --- -### Roles - Security in Superset is handled by Flask AppBuilder (FAB), an application development framework built on top of Flask. FAB provides authentication, user management, permissions and roles. Please read its [Security documentation](https://flask-appbuilder.readthedocs.io/en/latest/security.html). @@ -67,10 +65,20 @@ tables in the **Permissions** dropdown. To select the data sources you want to a You can then confirm with users assigned to the **Gamma** role that they see the objects (dashboards and slices) associated with the tables you just extended them. +### REST API for user & role management + +Flask-AppBuilder supports a REST API for user CRUD, but this feature is in beta and is not enabled by default in Superset. To enable this feature, set the following in your Superset configuration: + +```python +FAB_ADD_SECURITY_API = True +``` + +Once configured, the documentation for additional "Security" endpoints will be visible in Swagger for you to explore. + ### Customizing Permissions 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 +customization. FAB creates many permissions automatically for each model that is created (can_add, can_delete, can_show, can_edit, …) as well as for each view. On top of that, Superset can expose more granular permissions like **all_datasource_access**.