[v14][docs] MongoDB auto-user provisioning (#34939)

docs/config.json

@@ -1516,6 +1516,10 @@
               "title": "MariaDB",
               "slug": "/database-access/auto-user-provisioning/mariadb/"
             },
+            {
+              "title": "MongoDB",
+              "slug": "/database-access/auto-user-provisioning/mongodb/"
+            },
             {
               "title": "MySQL",
               "slug": "/database-access/auto-user-provisioning/mysql/"

docs/cspell.json

@@ -470,6 +470,7 @@
     "ingressclass",
     "initcontainers",
     "initdb",
+    "inprog",
     "insecureskipproxytlsverify",
     "ioreg",
     "isnt",

docs/pages/database-access/auto-user-provisioning.mdx

@@ -10,3 +10,4 @@ Currently, automatic user provisioning is supported for the following databases:
 - [Self-hosted and AWS RDS MySQL databases](./auto-user-provisioning/mysql.mdx)
 - [Self-hosted and AWS RDS MariaDB databases](./auto-user-provisioning/mariadb.mdx)
 - [AWS Redshift databases](./auto-user-provisioning/aws-redshift.mdx)
+- [Self-hosted MongoDB](./auto-user-provisioning/mongodb.mdx)

docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx

@@ -33,13 +33,13 @@ database, which will be created automatically if it doesn't exist.
 
 (!docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx protocol="postgres" uri="redshift-cluster-1.abcdefghijklm.us-east-1.redshift.amazonaws.com:5439" !)
 
-## Step 2/3. Configure Teleport role
+## Step 2/3. Configure a Teleport role
 
 (!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!)
 
 Users created within the database will:
 
-- Have the same name as Teleport username.
+- Have the same username as the authenticated Teleport user.
 - Be assigned the `teleport-auto-user` role.
 - Be assigned all roles from the Teleport user's role set that match the database.
   The role names must be valid and exist in the database.

docs/pages/database-access/auto-user-provisioning/mariadb.mdx

@@ -117,7 +117,7 @@ all-in-one role is set as the default role.
 
 (!docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx protocol="mysql" uri="localhost:3306" !)
 
-## Step 2/3. Configure Teleport role
+## Step 2/3. Configure a Teleport role
 
 (!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!)
 

docs/pages/database-access/auto-user-provisioning/mongodb.mdx

@@ -0,0 +1,125 @@
+---
+title: MongoDB Automatic User Provisioning 
+description: Configure automatic user provisioning for MongoDB.
+---
+
+(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!)
+
+- Teleport cluster v14.3 or above.
+- A self-hosted MongoDB database enrolled with your Teleport cluster. Follow
+  the [Teleport documentation](../guides/mongodb-self-hosted.mdx) to learn how
+  to enroll your database.
+- Ability to connect to and create user accounts in the target database.
+
+<Admonition type="note" title="Supported services">
+Automatic user provisioning is not compatible with MongoDB Atlas.
+</Admonition>
+
+## Step 1/3. Configure database admin
+
+Teleport uses the same authentication mechanism (X.509) when connecting as an
+admin user as for regular user connections.
+
+The admin user must have privileges within the database to create users and
+grant them privileges. The admin user must also have privileges to monitor user
+connections.
+
+First create a role on `admin` database with the following privileges:
+
+```bash
+db.getSiblingDB("admin").runCommand({
+    createRole: "teleport-admin-role",
+    privileges: [
+        { resource: { cluster: true }, actions: [ "inprog" ] },
+        { resource: { db: "", collection: "" }, actions: [ "grantRole", "revokeRole" ] },
+        { resource: { db: "$external", "collection": "" }, actions: [ "createUser", "updateUser", "dropUser", "viewUser", "setAuthenticationRestriction", "changeCustomData"] },
+    ],
+    roles: [],
+})
+```
+
+<Details title="Limit the grantRole action to specific databases">
+In the above example, the `grantRole` privilege is granted to the admin user
+for all databases in order for the admin user to assign roles from all
+databases, including the `admin` database.
+
+To enforce the principle of least privilege, you can limit the `grantRole` to
+only the databases that own the roles to be assigned to the auto-provisioned
+users:
+
+```bash
+db.getSiblingDB("admin").runCommand({
+    createRole: "teleport-admin-role",
+    privileges: [
+        { resource: { cluster: true }, actions: [ "inprog" ] },
+        { resource: { db: "", collection: "" }, actions: [ "revokeRole" ] },
+        { resource: { db: "$external", "collection": "" }, actions: [ "createUser", "updateUser", "dropUser", "viewUser", "setAuthenticationRestriction", "changeCustomData"] },
+        { resource: { db: "<db1>", collection: "" }, actions: [ "grantRole" ] },
+        { resource: { db: "<db2>", collection: "" }, actions: [ "grantRole" ] },
+        ...
+    ],
+    roles: [],
+})
+```
+</Details>
+
+Now create the admin user with this role:
+
+```bash
+db.getSiblingDB("$external").runCommand({
+  createUser: "CN=teleport-admin",
+  roles: [ { role: 'teleport-admin-role', db: 'admin' } ],
+})
+```
+
+(!docs/pages/includes/database-access/auto-user-provisioning/db-definition-self-hosted.mdx protocol="mongodb" uri="localhost:27017"!)
+
+
+## Step 2/3. Configure a Teleport role
+
+To specify the database roles a user should be assigned within the database,
+use the `db_roles` role option:
+
+```yaml
+kind: role
+version: v7
+metadata:
+  name: auto-db-users
+spec:
+  options:
+    # create_db_user_mode enables automatic user provisioning for matching databases
+    create_db_user_mode: keep
+  allow:
+    db_labels:
+      "*": "*"
+    db_names:
+    - "*"
+    # db_roles is a list of roles the database user will be assigned
+    db_roles:
+    - "readAnyDatabase@admin"
+    - "readWrite@db1"
+    - "myCustomRole@db2"
+    - "{{internal.db_roles}}"
+    - "{{external.db_roles}}"
+```
+
+(!docs/pages/includes/database-access/auto-user-provisioning/db_users_ignored.mdx!)
+
+(!docs/pages/includes/database-access/auto-user-provisioning/modes.mdx!)
+
+Users created within the database will:
+
+- Have the same username as the authenticated Teleport user.
+- Have `teleport-auto-user` set to `true` in the user's `customData`.
+- Be assigned all roles from the Teleport user's role set that match the database.
+  The role names must be valid and exist in the database.
+
+## Step 3/3. Connect to the database
+
+(!docs/pages/includes/database-access/auto-user-provisioning/connect.mdx gui="MongoDB Compass"!)
+
+## Next steps
+- Learn more about MongoDB [built-in roles](https://www.mongodb.com/docs/manual/reference/built-in-roles/) and [User-Defined Roles](https://www.mongodb.com/docs/manual/core/security-user-defined-roles/).
+- Connect using your [GUI database client](../../connect-your-client/gui-clients.mdx).
+- Learn about [role templating](../../access-controls/guides/role-templates.mdx#interpolation-rules).
+- Read automatic user provisioning [RFD](https://github.com/gravitational/teleport/blob/master/rfd/0113-automatic-database-users.md).

docs/pages/database-access/auto-user-provisioning/mysql.mdx

@@ -62,7 +62,7 @@ database, which will be created automatically if it doesn't exist.
 
 (!docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx protocol="mysql" uri="localhost:3306" !)
 
-## Step 2/3. Configure Teleport role
+## Step 2/3. Configure a Teleport role
 
 (!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!)
 

docs/pages/database-access/auto-user-provisioning/postgres.mdx

@@ -65,13 +65,13 @@ the database, which will be created automatically if it doesn't exist.
 (!docs/pages/includes/database-access/auto-user-provisioning/postgres15-grant-create.mdx!)
 </Admonition>
 
-## Step 2/3. Configure Teleport role
+## Step 2/3. Configure a Teleport role
 
 (!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!)
 
 Users created within the database will:
 
-- Have the same name as Teleport username.
+- Have the same username as the authenticated Teleport user.
 - Be a part of the `teleport-auto-user` role.
 - Be assigned all roles from the Teleport user's role set that match the database.
   The role names must be valid and exist in the database. See PostgreSQL

docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx

@@ -22,18 +22,6 @@ spec:
     - "{{external.db_roles}}"
 ```
 
-With automatic user provisioning, users always connect to the database with
-their Teleport username so the `db_users` role field is ignored for roles
-that have database user provisioning enabled.
+(!docs/pages/includes/database-access/auto-user-provisioning/db_users_ignored.mdx!)
 
-The available provisioning modes are:
-
-* `off`: Disables user provisioning.
-
-* `keep`: Enables user provisioning and disables users at session end. The user
-  will be stripped of all roles and the user account will be locked.
-
-* `best_effort_drop`: Enables user provisioning and, when the session ends,
-  drops the user if no resources depend on it. In cases where any resource
-  depends on the user, it falls back to disabling the user, mirroring the
-  behavior of `keep` mode.
+(!docs/pages/includes/database-access/auto-user-provisioning/modes.mdx!)

docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx

@@ -1,5 +1,5 @@
 {{ default="'teleport'" }}
-Next, enable the database admin on the Teleport database configuration:
+Next, configure the database admin user in the Teleport database configuration:
 
 <Tabs>
 <TabItem label="Static config">

docs/pages/includes/database-access/auto-user-provisioning/db-definition-self-hosted.mdx

@@ -0,0 +1,29 @@
+Next, configure the database admin user in the Teleport database configuration:
+
+<Tabs>
+<TabItem label="Static config">
+```yaml
+db_service:
+  enabled: "yes"
+  databases:
+  - name: "example"
+    protocol: "{{ protocol }}"
+    uri: "{{ uri }}"
+    admin_user:
+      name: "teleport-admin"
+```
+</TabItem>
+<TabItem label="Dynamic resource">
+```yaml
+kind: db
+version: v3
+metadata:
+  name: example
+spec:
+  protocol: "{{ protocol }}"
+  uri: "{{ uri }}"
+  admin_user:
+    name: "teleport-admin"
+```
+</TabItem>
+</Tabs>

docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx

@@ -1,4 +1,4 @@
-Next, enable the database admin on the Teleport database configuration:
+Next, configure the database admin user in the Teleport database configuration:
 
 <Tabs>
 <TabItem label="Static config">

docs/pages/includes/database-access/auto-user-provisioning/db_users_ignored.mdx

@@ -0,0 +1,3 @@
+With automatic user provisioning, users always connect to the database with
+their Teleport username so the `db_users` role field is ignored for roles
+that have database user provisioning enabled.

docs/pages/includes/database-access/auto-user-provisioning/modes.mdx

@@ -0,0 +1,11 @@
+The available provisioning modes are:
+
+* `off`: Disables user provisioning.
+
+* `keep`: Enables user provisioning and disables users at session end. The user
+  will be stripped of all roles and the user account will be locked.
+
+* `best_effort_drop`: Enables user provisioning and, when the session ends,
+  drops the user if no resources depend on it. In cases where any resource
+  depends on the user, it falls back to disabling the user, mirroring the
+  behavior of `keep` mode.