Fork me on GitHub

Database Access with MySQL on AWS

Setting up PAM Authentication with Teleport

Setting up PAM Authentication with Teleport

Length: 05:44


Enable IAM authentication

Teleport Database Access for AWS RDS and Aurora uses IAM authentication which can be enabled with the following steps.

Open Amazon RDS console and create a new database instance with IAM authentication enabled, or modify an existing one to turn it on. Make sure to use MySQL database type.

Aurora Serverless

Aurora Serverless does not support IAM authentication at the time of this writing so it can't be used with Database Access.

See Enabling and disabling IAM database authentication for more information.

Create IAM policy

To allow Teleport database service to log into the database instance using auth token, create an IAM policy and attach it to the user whose credentials the database service will be using. For example:

   "Version": "2012-10-17",
   "Statement": [
         "Effect": "Allow",
         "Action": [
         "Resource": [

The resource ARN in the policy has the following format:



  • region: AWS region where the database cluster is deployed.
  • account-id: AWS account ID the database cluster is deployed under.
  • db-cluster-resource-id: identifier for the database cluster, can be found under Configuration section in the RDS control panel.
  • db-user-name: name of the database account to associate with IAM authentication. Can be a wildcard.

See Creating and using an IAM policy for IAM database access for more information.

Create database user

Database accounts must have IAM authentication enabled in order to be allowed access. For MySQL:


By default the created user may not have access to anything and won't be able to connect so let's grant it some permissions:

GRANT ALL ON `%`.* TO 'alice'@'%';

See Creating a database account using IAM authentication for more information.

Setup Teleport Auth and Proxy services

Teleport Database Access for MySQL on AWS is available starting from 6.0 release.

Download the latest version of Teleport for your platform from our downloads page and follow the installation instructions.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt ACME protocol. We will assume that you have configured DNS records for and * to point to the Teleport node.

Generate Teleport config with ACME enabled:

$ teleport configure --acme [email protected] -o file
Web Proxy Port

Teleport uses TLS-ALPN-01 ACME challenge to validate certificate requests which only works on port 443. As such, in order to use ACME for certificate management, web proxy needs to be accessible on port 443.

Start Teleport Auth and Proxy services:

$ sudo teleport start

Database service requires a valid auth token to connect to the cluster. Generate one and save it in /tmp/token:

$ tctl tokens add --type=db

Create role and user

Create the role that will allow a user to connect to any database using any database account:

$ tctl --config=/path/to/teleport.yaml create <<EOF
kind: role
version: v4
  name: db
      '*': '*'
    - '*'
    - '*'

Create the user assigned the db role we've just created:

tctl --config=/path/to/teleport.yaml users add --roles=admin,db testuser

Start Database service with CLI flags

For a quick try-out, Teleport database service doesn't require a configuration file and can be launched using a single CLI command:

teleport db start \ --token=/tmp/token \ \ --name=aurora \ --protocol=mysql \ \ --aws-region=us-east-1 \ --labels=env=dev

Note that the --auth-server flag must point to the Teleport cluster's proxy endpoint because the database service always connects back to the cluster over a reverse tunnel.

Start Database service with config file

Below is an example of a database service configuration file that proxies a single AWS Aurora MySQL database:

  # The data_dir should be a different location if running on the same
  # machine as Teleport auth and proxy.
  data_dir: /var/lib/teleport-db
  nodename: teleport-db-instance
  # Teleport invitation token used to join a cluster.
  # can also be passed on start using --token flag
  auth_token: /tmp/token
  # Proxy address to connect to. Note that it has to be the proxy address
  # because database service always connects to the cluster over reverse
  # tunnel.
  enabled: "yes"
  # This section contains definitions of all databases proxied by this
  # service, can contain multiple items.
    # Name of the database proxy instance, used to reference in CLI.
  - name: "aurora"
    # Free-form description of the database proxy instance.
    description: "AWS Aurora MySQL"
    # Database protocol.
    protocol: "mysql"
    # Database address, example of a AWS Aurora endpoint in this case.
    uri: ""
    # AWS specific configuration, only required for RDS and Aurora.
      # Region the database is deployed in.
      region: us-east-1
    # Labels to assign to the database, used in RBAC.
      env: dev
  enabled: "no"
  enabled: "no"
  enabled: "no"

A single Teleport process can run multiple different services, for example multiple database access proxies as well as running other services such an SSH service or an application access proxy.

Start the database service:

teleport start --config=/path/to/teleport-db.yaml --token=/tmp/token

AWS credentials

When setting up Teleport database service with AWS RDS or Aurora, it must have an IAM role allowing it to connect to that particular database instance. An example of such a policy is shown in the Create IAM Policy section above. See Creating and using an IAM policy for IAM database access in AWS documentation.

Teleport database service uses the default credential provider chain to find AWS credentials. See Specifying Credentials for more information.


Once the database service has joined the cluster, login to see the available databases:

tsh login --user=testuser
tsh db ls

Name Description Labels

------ ---------------- --------

aurora AWS Aurora MySQL env=dev

Note that you will only be able to see databases your role has access to. See RBAC section for more details.

To connect to a particular database server, first retrieve credentials from Teleport using tsh db login command:

tsh db login aurora

You can be logged into multiple databases simultaneously.

You can optionally specify the database name and the user to use by default when connecting to the database instance:

tsh db login --db-user=root --db-name=mysql aurora

Once logged in, connect to the database:

tsh db connect aurora

The mysql command-line client should be available in PATH in order to be able to connect.

If you would like to see the native mysql shell connect command, run:

tsh db config --format=cmd aurora

To log out of the database and remove credentials:

Remove credentials for a particular database instance.

tsh db logout aurora

Remove credentials for all database instances.

tsh db logout
Have a suggestion or can’t find something?