docs: restored page on roles in security, executed other touchups, an…

…d… (#11978)

* Restored docs page on roles in security, executed other touchups, and renamed docs readme.txt to readme.md

* missed a url anchor on the security page

* fixed licensing issue and limited char width to 80

* fixed licensing issue and limited char width to 80

* whitespace experiments

* removed 2 periods

* staging whitespace

* addressed Robs feedback

* implemented robs second round of feedback on public_role_like

README.md

@@ -78,11 +78,11 @@ A modern, enterprise-ready business intelligence web application.
 
 Superset provides:
 * An intuitive interface to explore and visualize datasets, and
-    create interactive dashboards.
+    create interactive dashboards
 * A wide array of beautiful visualizations to showcase your data.
 * Easy, code-free, user flows to drill down and slice and dice the data
     underlying exposed dashboards. The dashboards and charts act as a starting
-    point for deeper analysis.
+    point for deeper analysis
 * A state of the art SQL editor/IDE exposing a rich metadata browser, and
     an easy workflow to create visualizations out of any result set.
 * An extensible, high granularity security model allowing intricate rules
@@ -133,7 +133,6 @@ A complete list of supported databases can be found
 
 [See in the documentation](https://superset.incubator.apache.org/docs/installation/installing-superset-using-docker-compose)
 
-
 ## Get Involved
 
 * Ask and answer questions on [StackOverflow](https://stackoverflow.com/questions/tagged/apache-superset)
@@ -152,14 +151,16 @@ how to set up a development environment.
 
 ## Resources
 
-* Superset 101 -- Getting Started Guide (From [Preset](https://preset.io) [Blog](https://preset.io/blog/))
+* Superset 101 -- Getting Started Guide (From [Preset Blog](https://preset.io/blog/))
   * [Installing Apache Superset Locally](https://preset.io/blog/2020-05-11-getting-started-installing-superset/)
   * [Installing Database Drivers](https://preset.io/blog/2020-05-18-install-db-drivers/)
   * [Connect Superset To Google Sheets](https://preset.io/blog/2020-06-01-connect-superset-google-sheets/)
   * [Create Your First Chart](https://preset.io/blog/2020-06-08-first-chart/)
   * [Create Time Series Charts](https://preset.io/blog/2020-06-26-timeseries-chart/)
-* [Docker image](https://hub.docker.com/r/preset/superset/)
+* [Docker image](https://hub.docker.com/r/apache/incubator-superset)
 * [Youtube Channel](https://www.youtube.com/channel/UCMuwrvBsg_jjI2gLcm04R0g)
   * [May 2020: Virtual Meetup Recording. Topics: 0.36 Overview, Committers Self-Intro, Roadmap](https://www.youtube.com/watch?v=tXGDmqjmcTs&t=20s)
   * [July 2020: Virtual Meetup Recording. Topics: Visualization Plugins, 0.37 Preview, Demo](https://www.youtube.com/watch?v=f6up5x_iRbI)
-* [So, You Want to Build a Superset Viz Plugin...](https://preset.io/blog/2020-07-02-hello-world/)
+  * [November 2020: Superset 1.0](https://www.youtube.com/watch?v=GwtWRUSEjk4)
+* [Building Custom Viz Plugins](https://superset.apache.org/docs/installation/building-custom-viz-plugins)
+* [Superset API](https://superset.apache.org/docs/rest-api)

docs/gatsby-node.js

@@ -634,4 +634,34 @@ exports.createPages = ({ actions }) => {
     toPath: '/docs/creating-charts-dashboards/first-dashboard',
     isPermanent: true,
   });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1000',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1000',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1001',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1001',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1002',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1002',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1003',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1003',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1004',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1004',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/issue_code_reference.html#issue-1005',
+    toPath: '/docs/miscellaneous/issue-codes#issue-1005',
+    isPermanent: true,
+  });
 };

docs/src/pages/docs/frequently-asked-questions-page.mdx

@@ -287,3 +287,11 @@ guarantees and are not recommended but may fit your use case temporarily:
 - using the ORM (SQLAlchemy) directly
 - using the internal FAB ModelView API (to be deprecated in Superset)
 - altering the source code in your fork
+
+
+### What Does Hours Offset in the Edit Dataset view do?
+
+
+In the Edit Dataset view, you can specify a time offset. This field lets you configure the
+number of hours to be added or subtracted from the time column.
+This can be used, for example, to convert UTC time to local time.

docs/src/pages/docs/installation/building-viz-plugins.mdx

@@ -207,3 +207,11 @@ to your plugin. These do a quick sanity check that the plugin actually loads cor
 through the basics of making sure that your controls are properly respected by modifying the
 resulting data and/or props of the plugin. Running `yarn test` from the root directory of
 `superset-ui` will run all the tests for plugins/packages, including your Hello World.
+
+### Deploying Custom Visualization to Production
+
+To deploy plugins to a production environment, you must have additional code
+inside Superset that includes the npm packages of your plugins so they can be installed in the frontend.
+
+
+One option is to build your Dockerfile so it contains your custom visualization packages.

docs/src/pages/docs/roadmap-page.mdx

@@ -5,14 +5,14 @@ route: /docs/roadmap
 ---
 
 ## Roadmap
+
+You can find the approximate public roadmap for Superset [here](https://github.com/apache-superset/superset-roadmap/projects/1).
+
 <a href="https://github.com/apache-superset/superset-roadmap/projects/1">
 <img src="/images/roadmap.png" style="max-width:100%; box-shadow: rgb(170, 170, 170) 0px 0px 3px 1px" />
 </a>
 
-We try our best to keep the
-[Superset Roadmap](https://github.com/apache-superset/superset-roadmap/projects/1) updated.
-
 Keep in mind that the roadmap represents only a subset of what's
 ahead. Many contributions come directly without ever making it onto the roadmap.
 Find out more about how the roadmap is managed in
-[SIP (Superset Improvement Proposal) 53 - Proposal to create a Superset public roadmap ](https://github.com/apache/incubator-superset/issues/10894)
+[SIP (Superset Improvement Proposal) 53](https://github.com/apache/incubator-superset/issues/10894)

docs/src/pages/docs/security-page.mdx

@@ -4,19 +4,149 @@ title: Security
 route: /docs/security
 ---
 
-## Security
+### 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).
+
+### Provided Roles
+
+Superset ships with a set of roles that are handled by Superset itself. You can assume
+that these roles will stay up-to-date as Superset evolves (and as you update Superset versions).
+
+Even though **Admin** users have the ability, we don't recommend that altering the
+permissions associated with each role (e.g. by removing or adding permissions to them). The permissions
+associated with each role will be re-synchronized to their original values when you run
+the **superset init** command (often done between Superset versions).
+
+### Admin
+
+Admins have all possible rights, including granting or revoking rights from other
+users and altering other people’s slices and dashboards.
+
+### Alpha
+
+Alpha users 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 users have limited access. They can only consume data coming from data sources
+they have been given 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.
+
+### sql_lab
+
+The **sql_lab** role grants access to SQL Lab. Note that while **Admin** users have access
+to all databases by default, both **Alpha** and **Gamma** users need to be given access on a per database basis.
+
+### Public
+
+To allow logged-out users to access some Superset features, you can use the `PUBLIC_ROLE_LIKE` config setting and assign it to another role whose permissions you want passed to this role.
+
+For example, by setting `PUBLIC_ROLE_LIKE = Gamma` in your `superset_config.py` file, you grant
+public role the same set of permissions as for the **Gamma** role. This is useful if one
+wants to enable anonymous users to view dashboards. Explicit grant on specific datasets is
+still required, meaning that you need to edit the **Public** role and add the public data sources to the role manually.
+
+### Managing Data Source Access for Gamma Roles
+
+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.
+
+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 on the dropdown and use the typeahead to search for your table names.
+
+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.
+
+### 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
+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**.
+
+**We do not recommend altering the 3 base roles as there are a set of assumptions that
+Superset is built upon**. It is possible though for you to create your own roles, and union them to existing ones.
+
+### Permissions
+
+Roles are composed of a set of permissions, and Superset has many categories of
+permissions. Here are the different categories of permissions:
+
+- Model & Action: models are entities like Dashboard, Slice, or User. Each model has
+a fixed set of permissions, like **can_edit**, **can_show**, **can_delete**, **can_list**, **can_add**,
+and so on. For example, you can allow a user to delete dashboards by adding **can_delete** on
+Dashboard entity to a role and granting this user that role.
+- Views: views are individual web pages, like the Explore view or the SQL Lab view.
+When granted to a user, they will see that view in its menu items, and be able to load that page.
+- Data source: For each data source, a permission is created. If the user does not have the
+`all_datasource_access permission` granted, the user will only be able to see Slices or explore the data sources that are granted to them
+- Database: Granting access to a database allows for the user to access all
+data sources within that database, and will enable the user to query that
+database in SQL Lab, provided that the SQL Lab specific permission have been granted to the user
+
+### Restricting Access to a Subset of Data Sources
+
+We recommend giving a user the **Gamma** role plus any other roles that would add
+access to specific data sources. We recommend that you create individual roles for
+each access profile. For example, the users on the Finance team might have access to a set of
+databases and data sources; these permissions can be consolidated in a single role.
+Users with this profile then need to be assigned the **Gamma** role as a foundation to
+the models and views they can access, and that Finance role that is a collection of permissions to data objects.
+
+A user can have multiple roles associated with them. For example, an executive on the Finance
+team could be granted **Gamma**, **Finance**, and the **Executive** roles. The **Executive**
+role could provide access to a set of data sources and dashboards made available only to executives.
+In the **Dashboards** view, a user can only see the ones they have access too
+based on the roles and permissions that were attributed.
+
+### Row Level Security
+
+Using Row Level Security filters (under the **Security** menu) you can create filters
+that are assigned to a particular table, as well as a set of roles.
+If you want members of the Finance team to only have access to
+rows where `department = "finance"`, you could:
+
+- Create a Row Level Security filter with that clause (`department = "finance"`)
+- Then assign the clause to the **Finance** role and the table it applies to
+
+The **clause** field, which can contain arbitrary text, is then added to the generated
+SQL statement’s WHERE clause. So you could even do something like create a filter
+for the last 30 days and apply it to a specific role, with a clause
+like `date_field > DATE_SUB(NOW(), INTERVAL 30 DAY)`. It can also support
+multiple conditions: `client_id = 6` AND `advertiser="foo"`, etc.
+
+All relevant Row level security filters will be combined together (under the hood,
+the different SQL clauses are combined using AND statements). This means it's
+possible to create a situation where two roles conflict in such a way as to limit a table subset to empty.
+
+For example, the filters `client_id=4` and `client_id=5`, applied to a role,
+ will result in users of that role having `client_id=4` AND `client_id=5`
+ added to their query, which can never be true.
+
+
+### Reporting Security Vulnerabilities
 
 Apache Software Foundation takes a rigorous standpoint in annihilating the security issues in its
 software projects. Apache Superset is highly sensitive and forthcoming to issues pertaining to its
 features and functionality.
 
+
 If you have apprehensions regarding Superset security or you discover vulnerability or potential
 threat, don’t hesitate to get in touch with the Apache Security Team by dropping a mail at
 security@apache.org. In the mail, specify the project name Superset with the description of the
 issue or potential threat. You are also urged to recommend the way to reproduce and replicate the
 issue. The security team and the Superset community will get back to you after assessing and
 analysing the findings.
 
+
 PLEASE PAY ATTENTION to report the security issue on the security email before disclosing it on
 public domain. The ASF Security Team maintains a page with the description of how vulnerabilities
 and potential threats are handled, check their web page for more details.

docs/src/pages/index.tsx

@@ -468,7 +468,7 @@ const Theme = () => {
                 )}
               </ul>
               <span className="databaseSub">
-                ... and any other
+                ... and many other
                 <a href="https://superset.apache.org/docs/databases/installing-database-drivers">
                   {' '}
                   compatible databases

superset/security/manager.py

@@ -623,7 +623,7 @@ def sync_role_definitions(self) -> None:
         if conf.get("PUBLIC_ROLE_LIKE_GAMMA", False):
             logger.warning(
                 "The config `PUBLIC_ROLE_LIKE_GAMMA` is deprecated and will be removed "
-                "in Superset 1.0. Please use `PUBLIC_ROLE_LIKE ` instead."
+                "in Superset 1.0. Please use `PUBLIC_ROLE_LIKE` instead."
             )
             self.copy_role("Gamma", self.auth_role_public, merge=True)