Fork me on GitHub
Teleport

Database Access with AWS RDS and Aurora for PostgreSQL and MySQL

Improve

This guide will help you to:

  • Install Teleport 8.0.7.
  • Set up Teleport to access your RDS instances and Aurora clusters.
  • Connect to your databases through Teleport.
Aurora Serverless

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

Prerequisites

  • Teleport version 8.0.7.
  • AWS account with RDS and Aurora databases and permissions to create and attach IAM policies.

Step 1/6. Install Teleport

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 teleport.example.com and *.teleport.example.com to point to the Teleport node.

Generate Teleport config with ACME enabled:

$ teleport configure --cluster-name=teleport.example.com --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

Step 2/6. Create Teleport user

Create a local Teleport user with the built-in access role:

$ tctl users add --roles=access alice

The access role allows users to see all connected database servers, but database names and accounts are restricted to the user's db_names and db_users traits. Normally, these traits come from the identity provider. For the local user you've just created you can update them manually to allow it to connect to any database as any database user.

First, export the user resource:

$ tctl get users/alice > alice.yaml

Update the resource to include the following traits:

traits:
  db_users:
  - "*"
  db_names:
  - "*"
Note

The db_names property only has effect on PostgreSQL and MongoDB database engines.

Update the user:

$ tctl create alice.yaml -f

For more detailed information about database access controls and how to restricted access see RBAC documentation.

Step 3/6. Configure IAM

Create IAM policy for Teleport

Teleport needs AWS IAM permissions to be able to:

  • Discover and register RDS instances and Aurora clusters.
  • Configure IAM authentication for them.

Go to the Policies page and create a managed IAM policy for the database agent.

The exact set of required permissions depends on whether you're connecting to RDS instances or Aurora clusters (or both), as well as the IAM identity your Teleport database agent will be using (user or role).

Use this policy if you're connecting to RDS instances and your Teleport database agent runs as IAM user (for example, uses AWS credentials file).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
                "rds:ModifyDBInstance",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy"
            ],
            "Resource": "*"
        }
    ]
}

Use this policy if you're connecting to RDS instances and your Teleport database agent runs as IAM role (for example, on an EC2 instance with attached IAM role).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
                "rds:ModifyDBInstance",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy"
            ],
            "Resource": "*"
        }
    ]
}

Use this policy if you're connecting to Aurora clusters and your Teleport database agent runs as IAM user (for example, uses AWS credentials file).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBClusters",
                "rds:ModifyDBCluster",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy"
            ],
            "Resource": "*"
        }
    ]
}

Use this policy if you're connecting to Aurora clusters and your Teleport database agent runs as IAM role (for example, on an EC2 instance with attached IAM role).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBClusters",
                "rds:ModifyDBCluster",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy"
            ],
            "Resource": "*"
        }
    ]
}

Create IAM permission boundary for Teleport

Since Teleport will be managing its own IAM policies for access to RDS and Aurora databases, you need to create a permission boundary to limit its effective range of permissions.

Create another managed policy that will serve as a permission boundary on the same Policies page.

The boundary should have the same set of permissions as the IAM policy you created above, plus rds-db:connect.

Use this permission boundary policy if you're connecting to RDS instances and your Teleport database agent runs as IAM user (for example, uses AWS credentials file).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
                "rds:ModifyDBInstance",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy",
                "rds-db:connect"
            ],
            "Resource": "*"
        }
    ]
}

Use this permission boundary policy if you're connecting to RDS instances and your Teleport database agent runs as IAM role (for example, on an EC2 instance with attached IAM role).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBInstances",
                "rds:ModifyDBInstance",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy",
                "rds-db:connect"
            ],
            "Resource": "*"
        }
    ]
}

Use this permission boundary policy if you're connecting to Aurora clusters and your Teleport database agent runs as IAM user (for example, uses AWS credentials file).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBClusters",
                "rds:ModifyDBCluster",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy",
                "rds-db:connect"
            ],
            "Resource": "*"
        }
    ]
}

Use this permission boundary policy if you're connecting to Aurora clusters and your Teleport database agent runs as IAM role (for example, on an EC2 instance with attached IAM role).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBClusters",
                "rds:ModifyDBCluster",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy",
                "rds-db:connect"
            ],
            "Resource": "*"
        }
    ]
}

Attach policy and boundary to IAM identity

Attach created policy and permission boundary to the IAM identity your Teleport database agent will be using. For example, if the agent runs as an IAM user:

IAM user

Self-managed IAM

If you prefer to self-manage IAM for your RDS databases, take a look at AWS reference for details.

Step 4/6. Start database agent

Database agent requires a valid auth token to connect to the cluster. Generate one by running the following command against your Teleport auth server and save it in /tmp/token on the node which will be running the database agent:

$ tctl tokens add --type=db

Create the database agent configuration e.g. in /etc/teleport.yaml:

teleport:
  data_dir: /var/lib/teleport
  auth_token: /tmp/token
  auth_servers:
  - teleport.example.com:3080 # Teleport proxy address to connect to
auth_service:
  enabled: "no"
proxy_service:
  enabled: "no"
db_service:
  enabled: "yes"
  aws:
  - types: ["rds"]
    regions: ["us-west-1"] # AWS regions to fetch databases from
    tags: # AWS database resource tags to match
      "*": "*"

Start the database agent:

teleport start --config=/etc/teleport.yaml

The agent will discover all RDS instances and Aurora clusters according to the configuration and register them in the cluster. It will also attempt to enable IAM auth and configure IAM access policies for the discovered databases. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.

AWS credentials

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

Step 5/6. Create database IAM user

Database users must allow IAM authentication in order to be used with Database Access for RDS. See below how to enable it for your database engine.

PostgreSQL users must have a rds_iam role:

CREATE USER alice;
GRANT rds_iam TO alice;

MySQL users must have RDS authentication plugin enabled:

CREATE USER alice IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';

Created user may not have access to anything by default so let's grant it some permissions:

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

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

Step 6/6. Connect

Once the database agent has started and joined the cluster, login to see the registered databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls

Name Description Labels

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

postgres-rds RDS instance in us-west-1 ...

aurora-mysql Aurora cluster in us-west-1 ...

Log into particular database using tsh db login command:

tsh db login postgres-rds
Tip

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=postgres --db-name=postgres postgres-rds

Now connect to the database:

tsh db connect postgres-rds
Note

The appropriate database command-line client (psql, mysql) should be available in PATH in order to be able to connect.

To log out of the database and remove credentials:

tsh db logout postgres-rds

Next steps

Have a suggestion or can’t find something?
IMPROVE THE DOCS