docs: BugHerd Tasks 88, 89, 90, 91 (apache#25567)

Co-authored-by: Sam Firke <[email protected]>

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

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`:
 

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**.