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

---
title: Database Access Getting Started Guide
sidebar_label: Getting Started
description: Getting started with Teleport database access and AWS Aurora PostgreSQL.
tags:
 - get-started
 - zero-trust
 - infrastructure-identity
page_type: how-to
---

(!docs/pages/includes/database-access/db-introduction.mdx dbType="PostgreSQL Amazon Aurora" dbConfigure="with IAM authentication"!)

## How it works

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
![Enroll RDS with a Self-Hosted Teleport Cluster](../../../img/database-access/guides/rds_selfhosted.png)
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
![Enroll RDS with a Cloud-Hosted Teleport Cluster](../../../img/database-access/guides/rds_cloud.png)
</TabItem>

</Tabs>

(!docs/pages/includes/database-access/how-it-works/iam.mdx db="Amazon Aurora" cloud="AWS"!)

## Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- An AWS account with a PostgreSQL Amazon Aurora database and permissions to create
  and attach IAM policies.

- A host, e.g., an EC2 instance, where you will run the Teleport Database
  Service.

- An AWS IAM principal for the host. For this guide, we assume that this is
  either an instance profile or an IAM user. If you select an instance profile,
  we assume the name of the attached role is `TeleportDatabaseServiceRole`. If
  you select a user, we assume the name of the user is
  `TeleportDatabaseServiceUser`.

  You can provide the IAM credentials to Teleport through a shared configuration
  file or environment variables. See
  [Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials)
  for details.

- (!docs/pages/includes/tctl.mdx!)

## Step 1/5. Set up Aurora

In order to allow Teleport connections to an Aurora instance, the instance 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 the "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 an IAM policy and attach it to the AWS user or service account
role. The Teleport Database Service will need to use the credentials of this AWS
user or service account in order to use this policy.

1. Add the following to a file called `database-service-policy.json`:

   ```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 the Teleport Database Service to connect to the Aurora
   instance as any database user using IAM auth.

   <Admonition
     type="note"
     title="Resource ID"
   >
     The database resource ID is shown on the Configuration tab of a particular
     database instance in the 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 the individual instance ID.
   </Admonition>

1. Create the policy:

   ```code
   $ aws iam create-policy --policy-name RDSConnect \
        --policy-document file://database-service-policy.json
   ```

1. Note the ARN of the policy you created for the next section. Assign it to
   <Var name="policy ARN" />.

1. Attach the `RDSConnect` policy to either an EC2 instance role or an IAM user:

   <Tabs>
   <TabItem label="EC2 instance">

   ```code
   $ aws iam attach-role-policy --role-name TeleportDatabaseServiceRole \
        --policy-arn <Var name="policy ARN" />
   ```

   </TabItem>
   <TabItem label="IAM user">

   ```code
   $ aws iam attach-user-policy --user-name TeleportDatabaseServiceUser \
        --policy-arn <Var name="policy ARN" />
   ```

   </TabItem>
   </Tabs>

1. 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 the AWS [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).

See the [Automatic User Provisioning](./auto-user-provisioning/postgres.mdx) guide for how to configure Teleport to create accounts for your PostgreSQL users on demand.

## Step 2/5. Configure the Teleport Database Service

(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!)

(!docs/pages/includes/database-access/alternative-methods-join.mdx!)

Install Teleport on the host where you will run the Teleport Database Service:

(!docs/pages/includes/install-linux.mdx!)

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">

On the node where you will run the Teleport Database Service, configure Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The `--proxy` flag must point to the
address of your Teleport Proxy Service.

```code
$ sudo teleport db configure create \
  --token=/tmp/token \
  --name=<Var name="aurora" /> \
  --proxy=<Var name="teleport.example.com" />:443 \
  --protocol=postgres \
  --uri=<Var name="postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com"/>:5432 \
  --aws-region=<Var name="us-west-1" /> \
  --output file:///etc/teleport.yaml
```

</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">

On the node where you will run the Teleport Database Service, configure Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The `--proxy` flag must point to the
address of your Teleport Cloud tenant.

```code
$ sudo teleport db configure create \
  --token=/tmp/token \
  --name=<Var name="aurora" /> \
  --proxy=<Var name="mytenant.teleport.sh" />:443 \
  --protocol=postgres \
  --uri=<Var name="postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com"/>:5432 \
  --aws-region=<Var name="us-west-1" /> \
  --output file:///etc/teleport.yaml
```

</TabItem>

</Tabs>

<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-15-set-up-aurora).
</Admonition>

## Step 3/5. Start the Database Service

Start the Teleport Database Service in your environment:

(!docs/pages/includes/start-teleport.mdx service="the Database Service"!)

## Step 4/5. Create a user and role

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

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

(!docs/pages/includes/create-role-using-web.mdx!)

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

<Tabs>
<TabItem scope={["oss"]} label="Teleport Community Edition">
```code
$ tctl users add --roles=access,db alice
```
</TabItem>
<TabItem scope={["enterprise", "cloud"]} label="Commercial">
```code
$ tctl users add --roles=access,requester,db alice
```
</TabItem>

</Tabs>

## Step 5/5. 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 in to Teleport with the user we've just created.

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">

```code
$ tsh login --proxy=<Var name="teleport.example.com" /> --user=<Var name="alice" />
```

</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">

```code
$ tsh login --proxy=<Var name="mytenant.teleport.sh" /> --user=<Var name="alice" />
```

</TabItem>

</Tabs>

Now we can inspect available databases:

```code
$ tsh db ls
```

Finally, connect to the database:

```code
$ tsh db connect --db-user=alice --db-name postgres aurora
```

(!docs/pages/includes/database-access/proxy-db-tunnel.mdx db="aurora" dbArgs="--db-user=alice --db-name=postgres"!)

### Auditing

(!docs/pages/includes/database-access/db-audit-events.mdx!)

## Troubleshooting

(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)

## 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/guides.mdx).
- Learn how to configure [GUI clients](../../connect-your-client/third-party/gui-clients.mdx).
- Learn about database access [role-based access control](./rbac.mdx).
- See [frequently asked questions](./faq.mdx).