Getting Started

In this getting started guide we will use Teleport Database Access to connect to a PostgreSQL AWS Aurora database.

Here's an overview of what we will do:

1. Configure AWS Aurora database with IAM authentication.
2. Download and install Teleport 7.3.2 and connect it to the Aurora database.
3. Connect to the Aurora database via Teleport.

Step 1/3. Setup Aurora

In order to allow Teleport connections to an Aurora instance, it needs to support IAM authentication.

If you don't have a database provisioned yet, create an instance of an Aurora PostgreSQL in the RDS control panel. Make sure to choose "Standard create" database creation method and enable "Password and IAM database authentication" in the Database Authentication dialog.

For existing Aurora instances, the status of IAM authentication is displayed on the Configuration tab and can be enabled by modifying the database instance.

Next, create the following IAM policy and attach it to the AWS user or service account. Teleport Database Service will need to use credentials of this AWS user or service account in order to use this policy.

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
             "rds-db:connect"
         ],
         "Resource": [
             "arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/*"
         ]
      }
   ]
}

This policy allows any database account to connect to the Aurora instance specified with resource ID using IAM auth.

Finally, connect to the database and create a database account with IAM auth support (or update an existing one). Once connected, execute the following SQL statements to create a new database account and allow IAM auth for it:

CREATE USER alice;
GRANT rds_iam TO alice;

For more information about connecting to the PostgreSQL instance directly, see Amazon documentation.

Step 2/3. Setup Teleport

Teleport Database Access is available starting from 6.0.0 release.

Download the appropriate version of Teleport for your platform from our downloads page.

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 node where you're launching Teleport.

Let's generate a Teleport config with ACME enabled:

teleport configure --cluster-name=teleport.example.com --acme [email protected]example.com > /tmp/teleport.yaml

Now start Teleport and point it to your Aurora database instance. Make sure to update the database endpoint and region appropriately.

sudo teleport start --config=/tmp/teleport.yaml \  --roles=proxy,auth,db \  --db-name=aurora \  --db-protocol=postgres \  --db-uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \  --db-aws-region=us-west-1

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

$ tctl create <<EOF
kind: role
version: v3
metadata:
  name: db
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_users:
    - '*'
EOF

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

tctl users add --roles=admin,db alice

Step 3/3. Connect

Now that Aurora is configured with IAM authentication, Teleport is running and the local user is created, we're ready to connect to the database.

Log into Teleport with the user we've just created. Make sure to use tsh version 6.0 or newer that includes Database Access support.

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

Now we can inspect available databases and retrieve credentials for the configured Aurora instance:

tsh db ls
tsh db login aurora

Finally, connect to the database using psql command shown in the output of tsh db login command, which looks similar to this:

psql "service=<cluster>-aurora user=alice dbname=postgres"

Next Steps

For the next steps, dive deeper into the topics relevant to your Database Access use-case, for example:

• Learn in more detail about AWS hosted PostgreSQL, MySQL, or GCP hosted PostgreSQL.
• Learn how to connect to a self-hosted PostgreSQL or MySQL.
• Learn how to configure GUI clients.
• Learn about Database Access role-based access control.
• See frequently asked questions.