Reorganize two Access Controls sections

CHANGELOG.md

@@ -3433,7 +3433,7 @@ can limit access by changing the options on the new `event` resource.
 The minimum set of Kubernetes permissions that need to be granted to Teleport
 proxies has been updated. If you use the Kubernetes integration, please make
 sure that the ClusterRole used by the proxy has [sufficient
-permissions](./docs/pages/kubernetes-access/manage-access/rbac.mdx).
+permissions](./docs/pages/kubernetes-access/controls.mdx).
 
 ##### Path prefix for etcd
 

docs/config.json

@@ -1174,18 +1174,8 @@
           ]
         },
         {
-          "title": "Configuring Access",
-          "slug": "/kubernetes-access/manage-access/",
-          "entries": [
-            {
-              "title": "Setting up Role-Based Access Controls",
-              "slug": "/kubernetes-access/manage-access/rbac/"
-            },
-            {
-              "title": "Federation",
-              "slug": "/kubernetes-access/manage-access/federation/"
-            }
-          ]
+          "title": "Setting up Role-Based Access Controls",
+          "slug": "/kubernetes-access/manage-access/"
         },
         {
           "title": "Access Controls Reference",
@@ -1354,13 +1344,7 @@
         },
         {
           "title": "Access Controls",
-          "slug": "/database-access/rbac/",
-          "entries": [
-            {
-              "title": "RBAC",
-              "slug": "/database-access/rbac/configuring-access/"
-            }
-          ]
+          "slug": "/database-access/rbac/"
         },
         {
           "title": "Automatic User Provisioning",
@@ -2759,11 +2743,6 @@
       "destination": "/application-access/guides/dynamodb/",
       "permanent": true
     },
-    {
-      "source": "/kubernetes-access/guides/federation/",
-      "destination": "/kubernetes-access/manage-access/federation/",
-      "permanent": true
-    },
     {
       "source": "/kubernetes-access/guides/dynamic-registration/",
       "destination": "/kubernetes-access/register-clusters/dynamic-registration/",
@@ -3198,6 +3177,16 @@
       "source": "/choose-an-edition/teleport-team/",
       "destination": "/choose-an-edition/teleport-cloud/get-started/",
       "permanent": true
+    },
+    {
+      "source": "/kubernetes-access/manage-access/rbac/",
+      "destination": "/kubernetes-access/manage-access/",
+      "permanent": true
+    },
+    {
+      "source": "/database-access/rbac/configuring-access/",
+      "destination": "/database-access/rbac/",
+      "permanent": true
     }
   ]
 }

docs/pages/access-controls/reference.mdx

@@ -99,7 +99,7 @@ Label              | `v3` Default   | `v4`, `v5` and `v6` Default
 `db_labels`         | `[{"*": "*"}]` | `[]`
 
 Role `v6` introduced a new field `kubernetes_resources` that allows
-fine-grained control over Kubernetes resources. See [Kubernetes RBAC](../kubernetes-access/manage-access/rbac.mdx) for more details.
+fine-grained control over Kubernetes resources. See [Kubernetes RBAC](../kubernetes-access/controls.mdx) for more details.
 
 Version              |  `kubernetes_resources`
 ------------------ | --------------

docs/pages/api/rbac.mdx

@@ -939,7 +939,7 @@ resources:
 
 - [Servers](../server-access/rbac.mdx)
 - [Databases](../database-access/rbac.mdx)
-- [Kubernetes clusters](../kubernetes-access/manage-access/rbac.mdx)
+- [Kubernetes clusters](../kubernetes-access/controls.mdx)
 - [Windows Desktops](../desktop-access/rbac.mdx)
 - [Applications](../application-access/controls.mdx)
 

docs/pages/database-access/getting-started.mdx

@@ -83,7 +83,7 @@ GRANT rds_iam TO alice;
 For more information about connecting to the PostgreSQL instance directly,
 see the AWS [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).
 
-See the [Automatic User Provisioning](./rbac/configuring-access.mdx) guide for how to configure Teleport to create accounts for your PostgreSQL users on demand.
+See the [Automatic User Provisioning](./rbac.mdx) guide for how to configure Teleport to create accounts for your PostgreSQL users on demand.
 
 ## Step 2/5. Configure the Teleport Database Service
 

docs/pages/database-access/introduction.mdx

@@ -51,6 +51,11 @@ with GitHub, execute a few SQL queries and observe them in the audit log:
 To learn more about configuring role-based access control for database access,
 check out the [RBAC](./rbac.mdx) section.
 
+Learn how to configure [automatic user
+provisioning](./auto-user-provisioning.mdx), which removes the need for creating
+individual user accounts in advance or using the same set of shared database
+accounts for all users.
+
 The [Architecture](./architecture.mdx) section provides a more in-depth look at
 Teleport Database Service internals such as networking and security.
 

docs/pages/database-access/rbac.mdx

@@ -1,13 +1,140 @@
 ---
-title: Database Access Control Guides
-description: Role-based access control guides for Teleport database access.
+title: Database Access RBAC
+description: Role-based access control (RBAC) for Teleport database access.
 ---
 
-These guides cover configuring access control policies for database users.
+Role-based access control (or RBAC, for short) allows administrators to set up
+granular access policies for databases connected to Teleport.
 
-Read the [RBAC](./rbac/configuring-access.mdx) guide to get a general understanding
-of how to configure Teleport roles to grant or deny access to your database users.
+An example of a policy could be, *"database administrators have access to
+everything, QA team and engineers have full access to staging databases, and
+engineers can gain temporary access to the production database in case of
+emergency"*.
 
-The [Automatic User Provisioning](./auto-user-provisioning.mdx) guides explain
-how to get Teleport to create database user accounts on demand for MySQL,
-PostgreSQL, and more.
+For a more general description of Teleport roles and examples see [RBAC](../access-controls/introduction.mdx), as
+this section focuses on configuring RBAC for database access.
+
+## Role configuration
+
+Teleport's "role" resource provides the following instruments for restricting
+database access:
+
+```yaml
+kind: role
+version: v5
+metadata:
+  name: developer
+spec:
+  allow:
+    # Label selectors for database instances this role has access to.
+    #
+    # These will be matched against the static/dynamic labels set on the
+    # database service.
+    db_labels:
+      environment: ["dev", "stage"]
+
+    # Database account names this role can connect as.
+    db_users: ["viewer", "editor"]
+
+    # Database names this role will be able to connect to.
+    #
+    # Note, this is not the same as the "name" field in "db_service", this is
+    # the database names within a particular database instance.
+    #
+    # Also note, this setting has effect only for PostgreSQL. It does not
+    # currently have any effect on MySQL databases/schemas.
+    db_names: ["main", "metrics", "postgres"]
+```
+
+It is possible to use wildcards to match any database names/users.
+
+For example, the following role permits access to any database/user within a
+production database except for the internal "postgres" database/user:
+
+```yaml
+kind: role
+version: v5
+metadata:
+  name: developer
+spec:
+  allow:
+    db_labels:
+      environment: ["prod"]
+    db_users: ["*"]
+    db_names: ["*"]
+  deny:
+    db_users: ["postgres"]
+    db_names: ["postgres"]
+```
+
+<Admonition
+  type="note"
+  title="Deny Rules"
+>
+  Deny rules will match greedily. In the example above, a database connection
+  attempting to use "postgres" database account (regardless of database instance
+  or database name) or "postgres" database name (regardless of database instance
+  or database account) will be rejected.
+</Admonition>
+
+## Database names
+
+There's a distinction in how different database servers handle logical databases
+which leads to a difference in how `db_names` role field is applied to a connection
+attempt.
+
+PostgreSQL supports multiple logical databases, and each logical database can
+contain multiple schemas. In order to change to a different database, a user
+disconnects from the current one and establishes a new connection. During a
+PostgreSQL connection attempt, `db_names` field is checked against the name
+of the logical database that the user is connecting to.
+
+In MySQL a logical "database" and a "schema" are synonyms for each other, and
+the scope of permissions a user has once connected is determined by the permission
+grants set on the account within the database. As such, `db_names` role field
+is not currently enforced on MySQL connection attempts.
+
+## Template variables
+
+Similar to other role fields, `db_*` fields support templating variables.
+
+The `external.xyz` traits are replaced with values from external [single
+sign-on](../access-controls/sso.mdx) providers. For OIDC, they will be
+replaced with the value of an "xyz" claim. For SAML, they are replaced 
+with an "xyz" assertion value. 
+
+For full details on how traits work in Teleport roles, see
+the [Teleport Access Controls
+Reference](../access-controls/reference.mdx).
+
+For example, here is what a role may look like if you want to assign allowed
+database names from the user's Okta `databases` assertion:
+
+```yaml
+spec:
+  allow:
+    db_names: ["{{external.databases}}"]
+```
+
+The `{{internal.db_users}}` and `{{internal.db_names}}` variables permit sharing
+allowed database accounts and names with remote clusters. They will be replaced
+with the respective properties of a remote user connecting from a root cluster.
+
+For example, suppose a user in the root cluster has the following role:
+
+```yaml
+spec:
+  allow:
+    db_users: ["postgres"]
+    db_names: ["postgres"]
+```
+
+The role on the leaf cluster can be set up to use the user's allowed database
+accounts and names:
+
+```yaml
+spec:
+  allow:
+    db_users: ["{{internal.db_users}}"]
+    db_names: ["{{internal.db_names}}"]
+```