diff --git a/docs/config.json b/docs/config.json index feb41eed29df5..a3eb732db08df 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1502,6 +1502,14 @@ "title": "Automatic User Provisioning", "slug": "/database-access/auto-user-provisioning/", "entries": [ + { + "title": "AWS Redshift", + "slug": "/database-access/auto-user-provisioning/aws-redshift/" + }, + { + "title": "MariaDB", + "slug": "/database-access/auto-user-provisioning/mariadb/" + }, { "title": "MySQL", "slug": "/database-access/auto-user-provisioning/mysql/" diff --git a/docs/pages/database-access/auto-user-provisioning.mdx b/docs/pages/database-access/auto-user-provisioning.mdx index 0f460d124d731..2e687c9bce5f5 100644 --- a/docs/pages/database-access/auto-user-provisioning.mdx +++ b/docs/pages/database-access/auto-user-provisioning.mdx @@ -3,8 +3,10 @@ title: Database Automatic User Provisioning description: Configure automatic user provisioning for databases. --- -(!docs/pages/includes/database-access/auto-user-provisioning-intro.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!) Currently, automatic user provisioning is supported for the following databases: -- [Self-hosted and RDS PostgreSQL databases](./auto-user-provisioning/postgres.mdx) -- [Self-hosted and RDS MySQL databases](./auto-user-provisioning/mysql.mdx) +- [Self-hosted and AWS RDS PostgreSQL databases](./auto-user-provisioning/postgres.mdx) +- [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) diff --git a/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx b/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx new file mode 100644 index 0000000000000..8e1a679ef12e2 --- /dev/null +++ b/docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx @@ -0,0 +1,57 @@ +--- +title: AWS Redshift Automatic User Provisioning +description: Configure automatic user provisioning for AWS Redshift. +--- + +(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!) + +## Prerequisites + +- Teleport cluster v14.1.3 or higher with a configured [AWS + Redshift](../guides/postgres-redshift.mdx) database. +- Ability to connect to and create user accounts in the target database. + + +Automatic user provisioning is not compatible with Redshift Serverless. + + +## Step 1/3. Configure database admin + +Teleport uses the same authentication mechanism (IAM authentication) 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 +processes and role assignments: +``` +CREATE USER "teleport-admin" WITH PASSWORD DISABLE; +GRANT ROLE "sys:superuser" TO "teleport-admin"; +``` + +Users created by Teleport will be assigned the `teleport-auto-user` role in the +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 + +(!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. +- 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/includes/database-access/auto-user-provisioning/username-conflict.mdx!) + +## Step 3/3. Connect to the database + +(!docs/pages/includes/database-access/auto-user-provisioning/connect.mdx gui="pgAdmin"!) + +## Next steps + +- 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/mariadb.mdx b/docs/pages/database-access/auto-user-provisioning/mariadb.mdx new file mode 100644 index 0000000000000..c52217c874507 --- /dev/null +++ b/docs/pages/database-access/auto-user-provisioning/mariadb.mdx @@ -0,0 +1,156 @@ +--- +title: MariaDB Automatic User Provisioning +description: Configure automatic user provisioning for MariaDB. +--- + +(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!) + +## Prerequisites + +- Teleport cluster v14.1.3 or higher with a configured [self-hosted + MariaDB](../guides/mysql-self-hosted.mdx) or [RDS MariaDB](../guides/rds.mdx) + database. +- Ability to connect to and create user accounts in the target database. + + +Automatic user provisioning is not compatible with MariaDB versions lower than +10.3.3 or 10.2.11. + + +## Step 1/3. Configure database admin + +(!docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx!) + +Teleport uses the same authentication mechanism when connecting as an admin +user as for regular user connections: X.509 for self-hosted databases and AWS +IAM for RDS. + +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 +processes and role assignments. + +In addition, a schema is required for the admin user to log into by default. +This schema is also used to store custom user attributes and stored procedures. + + + +The RDS MariaDB admin user must use `AWSAuthenticationPlugin` to allow IAM +authentication: +```sql +CREATE USER 'teleport-admin' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS'; +GRANT PROCESS, CREATE USER ON *.* TO 'teleport-admin'; +GRANT SELECT ON mysql.roles_mapping TO 'teleport-admin'; +GRANT UPDATE ON mysql.* TO 'teleport-admin'; -- For SET DEFAULT ROLE FOR + +CREATE DATABASE IF NOT EXISTS `teleport`; +GRANT ALL ON `teleport`.* TO 'teleport-admin' WITH GRANT OPTION; +``` + +Note that Teleport uses `teleport` as the name of the default schema but the +name is configurable in the Teleport database definition. Replace the database +name in the last two lines if you wish to use another database name. + + +In order for the admin user to grant a role to a database user, they must be +the "Admin" of the role. + +One way to achieve this is to create roles as the admin user, which +automatically designates the admin user as "Admin" of those roles. + +Alternatively, you can assign the admin user as the "Admin" of existing roles: +```sql +UPDATE mysql.roles_mapping SET User ='teleport-admin' WHERE Admin_option='Y' AND Role='role1'; +``` + +Replace `role1` with the name of the role that will be granted to +auto-provisioned users. + + + + + +The self-hosted MariaDB admin user must have X.509 authentication configured: +```sql +CREATE USER 'teleport-admin' REQUIRE SUBJECT '/CN=teleport-admin'; +GRANT PROCESS, CREATE USER ON *.* TO 'teleport-admin'; +GRANT SELECT ON mysql.roles_mapping TO 'teleport-admin'; +GRANT UPDATE ON mysql.* TO 'teleport-admin'; -- For SET DEFAULT ROLE FOR + +CREATE DATABASE IF NOT EXISTS `teleport`; +GRANT ALL ON `teleport`.* TO 'teleport-admin' WITH GRANT OPTION; +``` + +Note that Teleport uses `teleport` as the name of the default schema but the +name is configurable in the Teleport database definition. Replace the database +name in the last two lines if you wish to use another database name. + + +In order for the admin user to grant a role to a database user, they must be +the "Admin" of the role. + +One way to achieve this is to use the `WITH ADMIN` option when creating roles: +```sql +CREATE ROLE role1 WITH ADMIN 'teleport-admin'; +``` + +Alternatively, you can assign the admin user as the "Admin" of existing roles: +```sql +UPDATE mysql.roles_mapping SET User ='teleport-admin' WHERE Admin_option='Y' AND Role='role1'; +``` + +Replace `role1` with the name of the role that will be granted to +auto-provisioned users. + + + + + +Users created by Teleport will be assigned the `teleport-auto-user` role in the +database, which will be created automatically if it doesn't exist. + +During a MariaDB session, only one role is allowed to be active at a time. +Teleport creates an all-in-one role `tp-role-` and assigns it to the +created user. The true roles are then assigned to this all-in-one role and the +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 + +(!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!) + +Users created within the database will: + +- 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. The admin user must + be the "Admin" of these roles. See "Role Admin" section above for more + details. + +(!docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx database="MariaDB" limit="80" !) + +
+The original Teleport username will be saved as user attributes in the +`user_attributes` table in the default database. + +Database admins can search a particular Teleport username by: +```sql +SELECT * FROM teleport.user_attributes WHERE JSON_VALUE(Attributes,"$.user") = "teleport-user-name"; +``` + +In addition, the "hashed" in-database name will be set as `db_user` for +database queries in the Teleport Audit Logs, when the Teleport username is over +80 characters. +
+ +(!docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx!) + +## Step 3/3. Connect to the database + +(!docs/pages/includes/database-access/auto-user-provisioning/connect.mdx gui="MySQL Workbench"!) + +## Next steps + +- 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 32df0fb46a0bc..f0a7291879ec2 100644 --- a/docs/pages/database-access/auto-user-provisioning/mysql.mdx +++ b/docs/pages/database-access/auto-user-provisioning/mysql.mdx @@ -17,7 +17,7 @@ Automatic user provisioning is not compatible with MySQL versions lower than ## Step 1/3. Configure database admin -(!docs/pages/includes/database-access/auto-user-provisioning-configure-admin.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx!) Teleport uses the same authentication mechanism when connecting as an admin user as for regular user connections: X.509 for self-hosted databases and AWS IAM @@ -60,44 +60,11 @@ GRANT ALTER ROUTINE, CREATE ROUTINE, EXECUTE ON `teleport`.* TO 'teleport-admin' Users created by Teleport will be assigned the `teleport-auto-user` role in the database, which will be created automatically if it doesn't exist. -Next, enable the database admin on the Teleport Database Service configuration: - - - -```yaml -db_service: - enabled: "yes" - databases: - - name: "example" - protocol: "mysql" - uri: "localhost:3306" - admin_user: - name: "teleport-admin" -``` - - -```yaml -kind: db -version: v3 -metadata: - name: example -spec: - protocol: "mysql" - uri: "localhost:3306" - admin_user: - name: "teleport-admin" -``` - - - - -For auto-discovered cloud databases, the name of the admin user is taken from -the `teleport.dev/db-admin` label. - +(!docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx protocol="mysql" uri="localhost:3306" !) ## Step 2/3. Configure Teleport role -(!docs/pages/includes/database-access/auto-user-provisioning-common-teleport-role.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!) Users created within the database will: @@ -105,11 +72,7 @@ Users created within the database will: - 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. -MySQL limits usernames to 32 characters. When the Teleport username is within -this limit, the user created within the database will have the same name as the -Teleport username. When the Teleport username is over the 32 character limit, -the user created within the database will have the name in the format of -`tp-`. +(!docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx database="MySQL" limit="32" !)
The original Teleport username will be saved as user attributes within the @@ -130,13 +93,11 @@ database queries in the Teleport Audit Logs, when the Teleport username is over 32 characters.
-Note that in case of a name conflict where a user with the same name already -exists in the database and is not managed by Teleport (i.e. not assigned the -`teleport-auto-user` role), the connection will be aborted. +(!docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx!) ## Step 3/3. Connect to the database -(!docs/pages/includes/database-access/auto-user-provisioning-connect.mdx gui="MySQL Workbench"!) +(!docs/pages/includes/database-access/auto-user-provisioning/connect.mdx gui="MySQL Workbench"!) ## Next steps diff --git a/docs/pages/database-access/auto-user-provisioning/postgres.mdx b/docs/pages/database-access/auto-user-provisioning/postgres.mdx index 78a1439f55932..103ca0659df0d 100644 --- a/docs/pages/database-access/auto-user-provisioning/postgres.mdx +++ b/docs/pages/database-access/auto-user-provisioning/postgres.mdx @@ -3,7 +3,7 @@ title: PostgreSQL Automatic User Provisioning description: Configure automatic user provisioning for PostgreSQL. --- -(!docs/pages/includes//database-access/auto-user-provisioning-intro.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!) ## Prerequisites @@ -14,7 +14,7 @@ description: Configure automatic user provisioning for PostgreSQL. ## Step 1/3. Configure database admin -(!docs/pages/includes/database-access/auto-user-provisioning-configure-admin.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx!) Teleport will use the same authentication mechanism when connecting as an admin user as for regular user connections: X.509 for self-hosted databases and AWS @@ -59,44 +59,11 @@ to ensure that your configuration is correct. Users created by Teleport will be placed in the `teleport-auto-user` group in the database, which will be created automatically if it doesn't exist. -Next, enable the database admin on the Teleport database configuration: - - - -```yaml -db_service: - enabled: "yes" - databases: - - name: "example" - protocol: "postgres" - uri: "localhost:5432" - admin_user: - name: "teleport-admin" -``` - - -```yaml -kind: db -version: v3 -metadata: - name: example -spec: - protocol: "postgres" - uri: "localhost:5432" - admin_user: - name: "teleport-admin" -``` - - - - -For auto-discovered cloud databases, the name of the admin user is taken from -the `teleport.dev/db-admin` label. - +(!docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx protocol="postgres" uri="localhost:5432" !) ## Step 2/3. Configure Teleport role -(!docs/pages/includes/database-access/auto-user-provisioning-common-teleport-role.mdx!) +(!docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx!) Users created within the database will: @@ -107,13 +74,11 @@ Users created within the database will: [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) for information on how to create database roles. -Note that in case of a name conflict where a user with the same name already -exists in the database and is not managed by Teleport (i.e. not a part of the -`teleport-auto-user` group), the connection will be aborted. +(!docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx!) ## Step 3/3. Connect to the database -(!docs/pages/includes/database-access/auto-user-provisioning-connect.mdx gui="pgAdmin"!) +(!docs/pages/includes/database-access/auto-user-provisioning/connect.mdx gui="pgAdmin"!) ## Next steps diff --git a/docs/pages/database-access/rbac.mdx b/docs/pages/database-access/rbac.mdx index 4eeab1c21d487..a9e96d2b5c662 100644 --- a/docs/pages/database-access/rbac.mdx +++ b/docs/pages/database-access/rbac.mdx @@ -8,6 +8,6 @@ These guides cover configuring access control policies for database users. 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. -The [Automatic User Provisioning](./auto-user-provisioning.mdx) -guides explain how to get Teleport to create accounts for your PostgreSQL and -MySQL users on-demand. +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. 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 similarity index 100% rename from docs/pages/includes/database-access/auto-user-provisioning-common-teleport-role.mdx rename to docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx diff --git a/docs/pages/includes/database-access/auto-user-provisioning-configure-admin.mdx b/docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx similarity index 100% rename from docs/pages/includes/database-access/auto-user-provisioning-configure-admin.mdx rename to docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx diff --git a/docs/pages/includes/database-access/auto-user-provisioning-connect.mdx b/docs/pages/includes/database-access/auto-user-provisioning/connect.mdx similarity index 100% rename from docs/pages/includes/database-access/auto-user-provisioning-connect.mdx rename to docs/pages/includes/database-access/auto-user-provisioning/connect.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 new file mode 100644 index 0000000000000..9fa924b36655d --- /dev/null +++ b/docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx @@ -0,0 +1,41 @@ +Next, enable the database admin on the Teleport database configuration: + + + +```yaml +db_service: + enabled: "yes" + databases: + - name: "example" + protocol: "{{ protocol }}" + uri: "{{ uri }}" + admin_user: + name: "teleport-admin" + # Optional default database the admin user logs into. Default is + # "teleport" if not specified. + # default_database: teleport +``` + + +```yaml +kind: db +version: v3 +metadata: + name: example +spec: + protocol: "{{ protocol }}" + uri: "{{ uri }}" + admin_user: + name: "teleport-admin" + # Optional default database the admin user logs into. Default is + # "teleport" if not specified. + # default_database: teleport +``` + + + + +For auto-discovered cloud databases, the name of the admin user is taken from +the `teleport.dev/db-admin` label, and the default database is taken from the +`teleport.dev/db-admin-default-database` label. + 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 new file mode 100644 index 0000000000000..e354b3541298e --- /dev/null +++ b/docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx @@ -0,0 +1,34 @@ +Next, enable the database admin on 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" +``` + + + + +For auto-discovered cloud databases, the name of the admin user is taken from +the `teleport.dev/db-admin` label. + diff --git a/docs/pages/includes/database-access/auto-user-provisioning-intro.mdx b/docs/pages/includes/database-access/auto-user-provisioning/intro.mdx similarity index 100% rename from docs/pages/includes/database-access/auto-user-provisioning-intro.mdx rename to docs/pages/includes/database-access/auto-user-provisioning/intro.mdx diff --git a/docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx b/docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx new file mode 100644 index 0000000000000..0d0118d45789f --- /dev/null +++ b/docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx @@ -0,0 +1,3 @@ +Note that in case of a name conflict where a user with the same name already +exists in the database and is not managed by Teleport (i.e. not assigned the +`teleport-auto-user` role), the connection will be aborted. diff --git a/docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx b/docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx new file mode 100644 index 0000000000000..c9d60795d28e2 --- /dev/null +++ b/docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx @@ -0,0 +1,5 @@ +{{ database }} limits usernames to {{ limit }} characters. When the Teleport +username is within this limit, the user created within the database will have +the same name as the Teleport username. When the Teleport username is over the +{{ limit }} character limit, the user created within the database will have the +name in the format of `tp-`.