opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-24 16:17:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Database Automatic User Provisioning for MariaDB and Redshift (#33888)

Browse Source 
* [docs] Database Automatic User Provisioning for MariaDB and Redshift

* fix spelling
This commit is contained in:
STeve (Xin) Huang
2023-10-25 16:46:58 +00:00
committed by GitHub
parent a87be85859
commit 4c2dd577cb
15 changed files with 344 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config.json
+8
View File
@@ -1240,6 +1240,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/"
docs/pages/database-access/auto-user-provisioning.mdx
+5 -3
View File
@@ -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)
docs/pages/database-access/auto-user-provisioning/aws-redshift.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: AWS Redshift Automatic User Provisioning
description: Configure automatic user provisioning for AWS Redshift.
---
<Details
title="Version warning"
opened={true}
scope={["oss", "enterprise"]}
scopeOnly={true}
min="14.2"
>
Automatic user provisioning for AWS Redshift is available starting from
Teleport 14.2.
</Details>
(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!)
## Prerequisites
- Teleport cluster with a configured [AWS Redshift](../guides/postgres-redshift.mdx) 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 Redshift Serverless.
</Admonition>
## 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).
docs/pages/database-access/auto-user-provisioning/mariadb.mdx
+166
View File
@@ -0,0 +1,166 @@
---
title: MariaDB Automatic User Provisioning
description: Configure automatic user provisioning for MariaDB.
---
<Details
title="Version warning"
opened={true}
scope={["oss", "enterprise"]}
scopeOnly={true}
min="14.2"
>
Automatic user provisioning for MariaDB is available starting from Teleport
14.2.
</Details>
(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!)
## Prerequisites
- Teleport cluster 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.
<Admonition type="note" title="Supported versions">
Automatic user provisioning is not compatible with MariaDB versions lower than
10.3.3 or 10.2.11.
</Admonition>
## 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.
<Tabs>
<TabItem label="RDS MariaDB">
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.
<Admonition type="warning" title ="Role Admin">
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.
</Admonition>
</TabItem>
<TabItem label="Self-hosted MariaDB">
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.
<Admonition type="warning" title ="Role Admin">
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.
</Admonition>
</TabItem>
</Tabs>
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-<user>` 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" !)
<Details title="Tracking the name mapping">
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.
</Details>
(!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).
docs/pages/database-access/auto-user-provisioning/mysql.mdx
+6 -45
View File
@@ -27,7 +27,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
@@ -70,44 +70,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:
<Tabs>
<TabItem label="Static config">
```yaml
db_service:
enabled: "yes"
databases:
- name: "example"
protocol: "mysql"
uri: "localhost:3306"
admin_user:
name: "teleport-admin"
```
</TabItem>
<TabItem label="Dynamic resource">
```yaml
kind: db
version: v3
metadata:
name: example
spec:
protocol: "mysql"
uri: "localhost:3306"
admin_user:
name: "teleport-admin"
```
</TabItem>
</Tabs>
<Admonition type="tip" title="Auto-discovered databases">
For auto-discovered cloud databases, the name of the admin user is taken from
the `teleport.dev/db-admin` label.
</Admonition>
(!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:
@@ -115,11 +82,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-<base64-sha1-teleport-username>`.
(!docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx database="MySQL" limit="32" !)
<Details title="Tracking the name mapping">
The original Teleport username will be saved as user attributes within the
@@ -140,13 +103,11 @@ database queries in the Teleport Audit Logs, when the Teleport username is over
32 characters.
</Details>
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
docs/pages/database-access/auto-user-provisioning/postgres.mdx
+6 -41
View File
@@ -14,7 +14,7 @@ description: Configure automatic user provisioning for PostgreSQL.
Teleport 13.1.
</Details>
(!docs/pages/includes/database-access/auto-user-provisioning-intro.mdx!)
(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!)
## Prerequisites
@@ -24,7 +24,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
@@ -69,44 +69,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:
<Tabs>
<TabItem label="Static config">
```yaml
db_service:
enabled: "yes"
databases:
- name: "example"
protocol: "postgres"
uri: "localhost:5432"
admin_user:
name: "teleport-admin"
```
</TabItem>
<TabItem label="Dynamic resource">
```yaml
kind: db
version: v3
metadata:
name: example
spec:
protocol: "postgres"
uri: "localhost:5432"
admin_user:
name: "teleport-admin"
```
</TabItem>
</Tabs>
<Admonition type="tip" title="Auto-discovered databases">
For auto-discovered cloud databases, the name of the admin user is taken from
the `teleport.dev/db-admin` label.
</Admonition>
(!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:
@@ -117,13 +84,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
docs/pages/database-access/rbac.mdx
+3 -3
View File
@@ -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.
docs/pages/includes/database-access/auto-user-provisioning-common-teleport-role.mdx → docs/pages/includes/database-access/auto-user-provisioning/common-teleport-role.mdx
View File
docs/pages/includes/database-access/auto-user-provisioning-configure-admin.mdx → docs/pages/includes/database-access/auto-user-provisioning/configure-admin.mdx
View File
docs/pages/includes/database-access/auto-user-provisioning-connect.mdx → docs/pages/includes/database-access/auto-user-provisioning/connect.mdx
View File
docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx
+41
View File
@@ -0,0 +1,41 @@
Next, enable the database admin on 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"
# Optional default database the admin user logs into. Default is
# "teleport" if not specified.
# default_database: teleport
```
</TabItem>
<TabItem label="Dynamic resource">
```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
```
</TabItem>
</Tabs>
<Admonition type="tip" title="Auto-discovered databases">
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.
</Admonition>
docs/pages/includes/database-access/auto-user-provisioning/db-definition.mdx
+34
View File
@@ -0,0 +1,34 @@
Next, enable the database admin on 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>
<Admonition type="tip" title="Auto-discovered databases">
For auto-discovered cloud databases, the name of the admin user is taken from
the `teleport.dev/db-admin` label.
</Admonition>
docs/pages/includes/database-access/auto-user-provisioning-intro.mdx → docs/pages/includes/database-access/auto-user-provisioning/intro.mdx
View File
docs/pages/includes/database-access/auto-user-provisioning/username-conflict.mdx
+3
View File
@@ -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.
docs/pages/includes/database-access/auto-user-provisioning/username-hash.mdx
+5
View File
@@ -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-<base64-sha1-teleport-username>`.