[superset] branch master updated: docs: BugHerd Tasks 88, 89, 90, 91 (#25567)

[sf...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sfirke pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git


The following commit(s) were added to refs/heads/master by this push:
     new 59fc5a6184 docs: BugHerd Tasks 88, 89, 90, 91 (#25567)
59fc5a6184 is described below

commit 59fc5a6184d47c359fd830fd1a9bded531e3594c
Author: Multazim Deshmukh <57...@users.noreply.github.com>
AuthorDate: Fri Oct 13 20:48:08 2023 +0530

    docs: BugHerd Tasks 88, 89, 90, 91 (#25567)
    
    Co-authored-by: Sam Firke <sf...@users.noreply.github.com>
---
 docs/docs/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 e970cdc422..01e6274bbb 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 8a58c59964..3ba9d34fc7 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 5934af51df..45b603f2a7 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**.