teleport/docs/pages/database-access/getting-started.mdx

---
title: Database Access Getting Started Guide
description: Getting started with Teleport Database Access and AWS Aurora PostgreSQL.
---

# 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 (=teleport.version=) 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](https://console.aws.amazon.com/rds/home).
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.

```json
{
   "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.

<Admonition
  type="note"
  title="Resource ID"
>
  Database resource ID is shown on the Configuration tab of a particular
  database instance in RDS control panel, under "Resource id". For regular
  RDS database it starts with `db-` prefix. For Aurora, use the database
  cluster resource ID (`cluster-`), not individual instance ID.
</Admonition>

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:

```sql
CREATE USER alice;
GRANT rds_iam TO alice;
```

For more information about connecting to the PostgreSQL instance directly,
see Amazon [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).

## 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](https://goteleport.com/teleport/download).

Teleport requires a valid TLS certificate to operate and can fetch one automatically
using Let's Encrypt [ACME](https://letsencrypt.org/how-it-works/) 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:

```code
$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com > /tmp/teleport.yaml
```

<Admonition
  type="warning"
  title="Web Proxy Port"
>
  Teleport's ACME protocol integration currently requires web proxy to run on
  port 443 so open /tmp/teleport.yaml and update `proxy_service.web_listen_addr`
  and `proxy_service.public_addr` to use port 443 instead of the default 3080.
</Admonition>

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

```code
$ 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
```

<Admonition
  type="note"
  title="AWS Credentials"
>
  The node that connects to the database should have AWS credentials configured
  with the policy from [step 1](#step-13-setup-aurora).
</Admonition>

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

```bash
$ 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:

```code
$ tctl users add --roles=access,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.

```code
$ tsh login --proxy=teleport.example.com --user=alice
```

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

```code
$ 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:

```code
$ 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:

- Check out configuration [guides](./guides.mdx).
- Learn how to configure [GUI clients](./guides/gui-clients.mdx).
- Learn about Database Access [role-based access control](./rbac.mdx).
- See [frequently asked questions](./faq.mdx).