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

---
title: PostgreSQL Automatic User Provisioning
sidebar_label: PostgreSQL
description: Configure automatic user provisioning for PostgreSQL.
tags:
 - how-to
 - zero-trust
 - infrastructure-identity
page_type: how-to
---

{/* lint disable page-structure remark-lint */}

(!docs/pages/includes/database-access/auto-user-provisioning/intro.mdx!)

## Prerequisites

- Teleport cluster with a configured [self-hosted
  PostgreSQL](../enrollment/self-hosted/postgres-self-hosted.mdx) or [RDS
  PostgreSQL](../enrollment/aws/rds/mysql-postgres-mariadb.mdx) database. To configure
  permissions for database objects like tables, your cluster must be on version
  v15.2 or above.
- Ability to connect to and create user accounts in the target database.

<Admonition type="warning" title="RDS compatibility">
Automatic user provisioning is not compatible with RDS Aurora reader endpoints.
</Admonition>

## Step 1/3. Configure database admin

(!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
IAM for RDS. The admin user must have privileges within the database to create
users and grant them privileges, either for roles or concrete database objects.

<Tabs>
<TabItem label="RDS PostgreSQL">
The RDS PostgreSQL admin user must have the `rds_iam` role attached to allow IAM
authentication:

```sql
CREATE USER "teleport-admin" login createrole;
GRANT rds_iam TO "teleport-admin" WITH ADMIN OPTION;
```

Note that the RDS database must have IAM authentication enabled.

Refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) to make sure you are using the `rds_iam` role correctly for more information.

If the admin user needs to grant the `rds_superuser` role to auto-provisioned
users, the admin user must also be a `rds_superuser`:
```sql
GRANT rds_superuser TO "teleport-admin";
```

For PostgreSQL 16+, you must grant the `ADMIN` option to the admin user for each
PostgreSQL role that Teleport will assign to your Teleport user. For example, to
allow the admin user to grant and revoke role `reader`:
```sql
GRANT reader TO "teleport-admin" WITH ADMIN OPTION;
```
</TabItem>
<TabItem label="Self-hosted PostgreSQL">
The self-hosted PostgreSQL admin user must have X.509 authentication configured.

```sql
CREATE USER "teleport-admin" login createrole;
```

For PostgreSQL 16+, you must grant the `ADMIN` option to the admin user for each
PostgreSQL role that Teleport will assign to your Teleport user. For example, to
allow the admin user to grant and revoke role `reader`:
```sql
GRANT reader TO "teleport-admin" WITH ADMIN OPTION;
```

Note that the database must be configured to accept client certificate auth
for the admin user by having the following entries in `pg_hba.conf`:

```conf
hostssl all             all             ::/0                    cert
hostssl all             all             0.0.0.0/0               cert
```

Refer to the [self-hosted PostgreSQL guide](../enrollment/self-hosted/postgres-self-hosted.mdx#step-35-configure-your-postgresql-server)
to ensure that your configuration is correct.
</TabItem>
</Tabs>

<Admonition type="note" title="Database Access Controls for `teleport-admin`">
When [Database Access Controls](../rbac.mdx) feature is in use, the
`teleport-admin` should have permissions to relevant database objects. You can
grant `teleport-admin` the `SUPERUSER` option for self-hosted databases, or the
`rds_superuser` role for RDS databases.

For improved security through the principle of least privilege, you can also
assign permissions directly to specific database objects. For example:

```sql
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA schema1, schema2, schema3 TO "teleport-admin";
```
</Admonition>

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.

(!docs/pages/includes/database-access/auto-user-provisioning/db-definition-default-dbname.mdx protocol="postgres" uri="localhost:5432" default="the same database that the user is accessing" !)

## Step 2/3. Configure a Teleport role

Database permissions are associated with a Teleport role, which can either allocate predefined database roles (configured in each database) or define specific database object permissions directly. Teleport grants these permissions for the duration of the connection.

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

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

<Tabs>
<TabItem label="Database roles">

To specify the database roles a user should be assigned within the database,
use the `db_roles` role option. To create the role below, open a file called
`db-user-creator.yaml` with the following content:

```yaml
kind: role
version: v7
metadata:
  name: db-user-creator
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:
    - reader
    - "{{internal.db_roles}}"
    - "{{external.db_roles}}"
```

Create the role:

```code
$ tctl create -f db-user-creator.yaml
```

The provisioned database user 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.
See PostgreSQL [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html) for information on how to create database roles.

</TabItem>
<TabItem label="Database Access Controls">

Required Teleport version: v15.2 or above.

Use `spec.allow.db_permissions` section in a user role to specify object
permissions given user should have. To create the role below, open a file called
`all-table-reader.yaml` with the following content:

```yaml
kind: role
metadata:
  name: all-table-reader
spec:
  options:
    # create_db_user_mode enables automatic user provisioning for matching databases
    create_db_user_mode: keep
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_permissions:
    # grant `SELECT` on all tables in `public` schema.
    - match:
        # object labels to match
        object_kind: table
        schema: public
      permissions:
      - SELECT
version: v7
```

Create the role:

```code
$ tctl create -f all-table-reader.yaml
```

You can define your own labels for database objects, applying them based on customizable import rules. These custom labels, such as `owner` or `environment`, can then be utilized when granting permissions.

For additional information, refer to the [Database Access Controls](../rbac.mdx) page.

</TabItem>
</Tabs>


Users created within the database will:
- Have the same username as the authenticated Teleport user.
- Be a part of the `teleport-auto-user` role.
- Will be assigned permissions according to the chosen mechanism.

(!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/db-access-webui-ad.mdx dbType="PostgreSQL"!)

## Troubleshooting

### User does not have CONNECT privilege error

You may encounter the following error when the admin user or the roles assigned
to the auto-provisioned user do not have permission to connect to the target
database:

```code
$ tsh db connect --db-name <database> example
...
FATAL: permission denied for database "<database>"
DETAIL: User does not have CONNECT privilege.
```

Make sure `CONNECT` is granted to the admin user and the respective roles:
```sql
GRANT CONNECT ON DATABASE <database> to "teleport-admin";
GRANT CONNECT ON DATABASE <database> to "reader";
```

### Cannot execute in a read-only transaction error

You may encounter the following error when connecting to an Amazon RDS Aurora
reader endpoint:
```code
$ tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused
...
ERROR: cannot execute CREATE ROLE in a read-only transaction (SQLSTATE 25006)
```

Database auto-user provisioning is not compatible with RDS Aurora reader
endpoints. Please use auto-user provisioning on the primary endpoints.

### No schema has been selected error

You may encounter the following error when connecting if the admin user does
not have `USAGE` permission on the schema:
```code
$ tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused
...
ERROR: no schema has been selected to create in (SQLSTATE 3F000)
```

To fix this, make sure that the admin user is granted `USAGE` and `CREATE` on
schema `public` in the target database:
```sql
GRANT USAGE ON SCHEMA public TO "teleport-admin";
GRANT CREATE ON SCHEMA public TO "teleport-admin";
```

### Permission denied to grant role "rds_iam"

You may encounter the following error when connecting to an RDS database:
```code
$ tsh db connect --db-name <database> example
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused
...
ERROR: permission denied to grant role "rds_iam" (SQLSTATE 42501)
```

This happens when the admin user does not have permission to grant the
"rds_iam" role to other users. To fix this, grant the "rds_iam" role with the
`ADMIN` option to the admin user:
```sql
GRANT rds_iam TO "teleport-admin" WITH ADMIN OPTION;
```

### Use your mapped remote username error

(!docs/pages/includes/database-access/auto-user-provisioning/troubleshooting-remote-username.mdx!)

(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)

(!docs/pages/includes/database-access/psql-ssl-syscall-error.mdx!)

### Amazon RDS Blue/Green deployment enters a state of "Replication degraded"

Amazon RDS Blue/Green deployment may enter a state of "Replication degraded"
when auto-user provisioning is used to connect to the database.

This occurs due to a [limitation in PostgreSQL logical
replication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments-overview.html#blue-green-deployments-limitations-postgres)
for Blue/Green deployments as Data Definition Language (DDL) statements cannot
be replicated. Consequently, Amazon RDS will enter the "Replication degraded"
state when a DDL change is detected.

It is recommended to disable database auto-user provisioning before starting
the Blue/Green deployment.

If the database is auto-discovered by Teleport, you can temporarily remove the
`teleport.dev/db-admin` AWS resource tag. For a database registered using
either static config or a dynamic `db` resource, you can temporarily remove the
`admin_user` setting.

Once auto-user provisioning is disabled, you can still connect as the database
admin user through Teleport.

## Next steps

- Connect using your [GUI database
  client](../../../connect-your-client/third-party/gui-clients.mdx).
- Learn about [role
  templating](../../../zero-trust-access/rbac-get-started/role-templates.mdx).
- Read automatic user provisioning [RFD](https://github.com/gravitational/teleport/blob/8ff3d34581424302182c217e4d8d3be45bf2b0b7/rfd/0113-automatic-database-users.md).
- Read database permission management [RFD](https://github.com/gravitational/teleport/blob/8ff3d34581424302182c217e4d8d3be45bf2b0b7/rfd/0151-database-permission-management.md).
- The `internal.db_roles` traits we illustrated in this guide
  are replaced with values from the Teleport local user database. For full
  details on how variable expansion works in Teleport roles, see the [Teleport
  Access Controls Reference](../../../reference/access-controls/roles.mdx).