diff --git a/docs/config.json b/docs/config.json index 962f647bf3946..a9f7289da3fd9 100644 --- a/docs/config.json +++ b/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/" diff --git a/docs/cspell.json b/docs/cspell.json index d9ed977b82d4b..aabbc0f26e8b1 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -470,6 +470,7 @@ "ingressclass", "initcontainers", "initdb", + "inprog", "insecureskipproxytlsverify", "ioreg", "isnt", diff --git a/docs/pages/database-access/auto-user-provisioning.mdx b/docs/pages/database-access/auto-user-provisioning.mdx index 2e687c9bce5f5..f04d14b1278d1 100644 --- a/docs/pages/database-access/auto-user-provisioning.mdx +++ b/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) diff --git a/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx b/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx index 8e1a679ef12e2..f3f7a540edc50 100644 --- a/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx +++ b/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. diff --git a/docs/pages/database-access/auto-user-provisioning/mariadb.mdx b/docs/pages/database-access/auto-user-provisioning/mariadb.mdx index 7088cc1f4ef64..28b695a758d6c 100644 --- a/docs/pages/database-access/auto-user-provisioning/mariadb.mdx +++ b/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!) diff --git a/docs/pages/database-access/auto-user-provisioning/mongodb.mdx b/docs/pages/database-access/auto-user-provisioning/mongodb.mdx new file mode 100644 index 0000000000000..a162aad8acbef --- /dev/null +++ b/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. + + +Automatic user provisioning is not compatible with MongoDB Atlas. + + +## 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: [], +}) +``` + +
+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: "", collection: "" }, actions: [ "grantRole" ] }, + { resource: { db: "", collection: "" }, actions: [ "grantRole" ] }, + ... + ], + roles: [], +}) +``` +
+ +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). diff --git a/docs/pages/database-access/auto-user-provisioning/mysql.mdx b/docs/pages/database-access/auto-user-provisioning/mysql.mdx index f0a7291879ec2..a9e1cba5d3189 100644 --- a/docs/pages/database-access/auto-user-provisioning/mysql.mdx +++ b/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!) diff --git a/docs/pages/database-access/auto-user-provisioning/postgres.mdx b/docs/pages/database-access/auto-user-provisioning/postgres.mdx index f264b9097d2bc..b9e3d2fcd6ddc 100644 --- a/docs/pages/database-access/auto-user-provisioning/postgres.mdx +++ b/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!) -## 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 diff --git a/docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx b/docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx index 99ce797727977..81c820e8592ad 100644 --- a/docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx +++ b/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!) diff --git a/docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx b/docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx index 6b1722bc48ef4..8db14c3ab953a 100644 --- a/docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx +++ b/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: diff --git a/docs/pages/includes/database-access/auto-user-provisioning/db-definition-self-hosted.mdx b/docs/pages/includes/database-access/auto-user-provisioning/db-definition-self-hosted.mdx new file mode 100644 index 0000000000000..c238a65926a17 --- /dev/null +++ b/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: + + + +```yaml +db_service: + enabled: "yes" + databases: + - name: "example" + protocol: "{{ protocol }}" + uri: "{{ uri }}" + admin_user: + name: "teleport-admin" +``` + + +```yaml +kind: db +version: v3 +metadata: + name: example +spec: + protocol: "{{ protocol }}" + uri: "{{ uri }}" + admin_user: + name: "teleport-admin" +``` + + diff --git a/docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx b/docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx index e354b3541298e..c2a7749c46055 100644 --- a/docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx +++ b/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: diff --git a/docs/pages/includes/database-access/auto-user-provisioning/db_users_ignored.mdx b/docs/pages/includes/database-access/auto-user-provisioning/db_users_ignored.mdx new file mode 100644 index 0000000000000..c61b2f6dc6da6 --- /dev/null +++ b/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. diff --git a/docs/pages/includes/database-access/auto-user-provisioning/modes.mdx b/docs/pages/includes/database-access/auto-user-provisioning/modes.mdx new file mode 100644 index 0000000000000..15b111f481c25 --- /dev/null +++ b/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.