Fork me on GitHub


Database Automatic User Provisioning

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

Automatic user provisioning for PostgreSQL is available starting from Teleport 13.1.

Teleport can automatically create users in your database, removing the need for having to create each individual user account in advance, or using the same set of shared database accounts for all users.

Supported databases

Currently, automatic user provisioning is only supported for self-hosted and RDS PostgreSQL databases.


Step 1/3. Configure database admin

Teleport should be able to connect to the database as a user that can create other users and assign them roles. We recommend creating a separate user designated specifically for Teleport automatic user provisioning. Let's call it teleport-admin.

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.

The RDS PostgreSQL admin user must have the rds_iam role attached to allow IAM authentication:

CREATE USER "teleport-admin" login createrole;
GRANT rds_iam TO "teleport-admin";

Note that the RDS database must have IAM authentication enabled.

Refer to the AWS documentation to make sure you are using the rds_iam role correctly. for more information.

The self-hosted PostgreSQL admin user must have X.509 authentication configured.

CREATE USER "teleport-admin" login createrole;

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:

hostssl all             all             ::/0                    cert
hostssl all             all                  cert

Refer to the self-hosted PostgreSQL guide 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.

Teleport will not delete the automatically created user at the end of the session. Instead, the user will be stripped of all roles, updated with nologin trait and reactivated during the next connection.

Next, enable the database admin on the Teleport database configuration:

  enabled: "yes"
  - name: "example"
    protocol: "postgres"
    uri: "localhost:5432"
      name: "teleport-admin"
kind: db
version: v3
  name: example
  protocol: "postgres"
  uri: "localhost:5432"
    name: "teleport-admin"
Auto-discovered databases

For auto-discovered cloud databases, the name of the admin user is taken from the label.

Step 2/3. Configure Teleport role

To specify the database roles a user should be assigned within the database, use the db_roles role option:

kind: role
version: v7
  name: auto-db-users
    # create_db_user enables automatic user provisioning for matching databases
    create_db_user: true
      "*": "*"
    - "*"
    # db_roles is a list of roles the database user will be assigned
    - reader
    - "{{internal.db_roles}}"
    - "{{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.

User created within the database will:

  • Have the same name as Teleport username.
  • 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 CREATE ROLE 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.

Step 3/3. Connect to the database

Now, log into your Teleport cluster and connect to the database:

$ tsh login
$ tsh db connect example

If using a GUI database client like pgAdmin, make sure to use your Teleport username as a database username. tsh db connect will default to it automatically when connecting to a database with user provisioning enabled.

Next steps