Database Access with AWS RDS and Aurora for PostgreSQL, MySQL and MariaDB

Access to AWS or RDS Aurora databases can be provided by Teleport Database Access. This allows for fine-grain access control through Teleport's RBAC.

This guide demonstrates how to use Teleport to connect to AWS or RDS Aurora databases.

In this guide, you will:

1. Configure AWS RDS or Aurora databases with IAM authentication.
2. Join the AWS RDS or Aurora databases to your Teleport cluster.
3. Connect to the AWS RDS or Aurora database via the Teleport Database Service.

• Self-Hosted
• Teleport Enterprise Cloud

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

Prerequisites

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

• AWS account with RDS and Aurora databases and permissions to create and attach IAM policies. Your RDS and Aurora databases must have password and IAM authentication enabled.
• A Linux host or Amazon Elastic Kubernetes Service cluster where you will run the Teleport Database Service, which proxies connections to your RDS databases.
• A running Teleport Discovery Service if you plan to use Database Auto-Discovery.
• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  14.0.0
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

If you plan to run the Teleport Database Service on Kubernetes, you will need the following:

• The aws CLI in your PATH. Install it by following the AWS documentation.

• An IAM OIDC provider running in your Kubernetes cluster. See the AWS documentation for how to create an IAM OIDC provider.

  To check whether you have an IAM OIDC provider running in your cluster, run the following aws command, assigning eks-region to the region where your EKS cluster is running and cluster-name to the name of your Kubernetes cluster:

  aws --region=eks-region eks describe-cluster --name cluster-name --query "cluster.identity.oidc.issuer" --output text

  If you have an IAM OIDC provider associated with your cluster, this command will print its ID.

• The jq CLI tool, which we use to process JSON data in this guide.

Step 1/6. Create a Teleport user

tctl users add \  --roles=access \  --db-users=\* \  --db-names=\* \  alice

tctl users add \  --roles=access,requester \  --db-users=\* \  --db-names=\* \  alice

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

Step 2/6. Create a Database Service configuration

In this section, you will configure the Teleport Database Service. To do so, you will:

• Create a join token for the service to demonstrate trust with your Teleport cluster.
• Set up your package manager so you can install and run the Database Service.
• Generate a configuration for the Database Service.

Create a join token

Establish trust between the Teleport Database Service and your Teleport cluster by creating a join token.

Generate a join token by running the following command on your workstation:

tctl tokens add --type=db

The next step depends on how you plan to run the Teleport Database Service:

Prepare your environment

Next, get your environment ready to run the Teleport Database Service:

curl https://goteleport.com/static/install.sh | bash -s 13.3.9

curl https://goteleport.com/static/install.sh | bash -s 14.0.0

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent

sudo apt-get install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"
sudo yum install teleport-ent
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")
sudo yum install teleport-ent
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"

Install teleport
sudo dnf install teleport-ent

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

sudo dnf install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent

sudo zypper install teleport-ent-fips

curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

sudo teleport db configure create \   -o file \   --proxy=mytenant.teleport.sh:443 \   --token=/tmp/token \   --dynamic-resources-labels env=prod

discovery_service:
  enabled: "yes"
  aws:
  - types: ["rds"]
    regions: ["us-west-1"]
    tags:
      "env": "prod" # Match database resource tags where tag:env=prod

helm repo add teleport https://charts.releases.teleport.dev

helm repo update

Step 3/6. Create IAM policies for Teleport

The Teleport Database Service needs AWS IAM permissions to be able to:

• Configure IAM authentication.

In this step, we will show you how to provide the Teleport Database Service access to AWS credentials:

AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>

teleport discovery bootstrap \  --attach-to-role arn:aws:iam::aws-account-id:role/discovery-iam-role-name \  --policy-name TeleportDatabaseDiscovery \  --database-service-role arn:aws:iam::aws-account-id:role/database-iam-role-name \  --database-service-policy-name TeleportDatabaseAccess \  -c path to Discovery's teleport.yaml

teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser

teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole

teleport db configure bootstrap -c /etc/teleport.yaml --manual --attach-to-user arn:aws:iam::123456789012:user/TeleportUser

teleport db configure bootstrap -c /etc/teleport.yaml --manual --attach-to-role arn:aws:iam::123456789012:role/TeleportRole

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

aws iam create-policy --policy-name teleport-rds-policy --policy-document file://connect.json
{    "Policy": {        "PolicyName": "teleport-rds-policy",        "PolicyId": "000000000000000000000",        "Arn": "arn:aws:iam::000000000000:policy/teleport-rds-policy",        "Path": "/",        "DefaultVersionId": "v1",        "AttachmentCount": 0,        "PermissionsBoundaryUsageCount": 0,        "IsAttachable": true,        "CreateDate": "2023-07-13T18:03:08+00:00",        "UpdateDate": "2023-07-13T18:03:08+00:00"    }}

aws eks describe-cluster --name cluster-name --region eks-region | jq -r .cluster.identity.oidc.issuer | grep -Eo "[A-Z0-9]+$"
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

{    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Principal": {                "Federated": "arn:aws:iam::aws-account:oidc-provider/oidc.eks.eks-region.amazonaws.com/id/oidc-issuer"            },            "Action": "sts:AssumeRoleWithWebIdentity",            "Condition": {                "StringEquals": {                    "oidc.eks.eks-region.amazonaws.com/id/oidc-issuer:aud": "sts.amazonaws.com"                }            }        }    ]}

aws iam create-role --role-name teleport-rds-role --assume-role-policy-document file://trustpolicy.json

aws iam attach-role-policy --policy-arn arn:aws:iam::aws-account:policy/teleport-rds-policy --role-name teleport-rds-role

Step 4/6. Start the Database Service

Start the Teleport Database Service in your environment:

sudo systemctl enable teleport
sudo systemctl start teleport

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

tctl tokens ls
Token                            Type Labels Expiry Time (UTC)-------------------------------- ---- ------ ----------------------------abcd123-insecure-do-not-use-this Db          14 Jun 23 21:21 UTC (20m15s)

authToken: tokenproxyAddr: example.teleport.sh:443roles: dbdatabases:- name: example  uri: "rds-uri"  protocol: "postgres"  static_labels:    env: dev  aws:    region: "rds-region"annotations:  serviceAccount:    eks.amazonaws.com/role-arn: arn:aws:iam::aws-account:role/teleport-rds-role

helm -n teleport install teleport-kube-agent teleport/teleport-kube-agent \  --values values.yaml --create-namespace

kubectl -n teleport get pods
NAME                    READY   STATUS    RESTARTS   AGEteleport-kube-agent-0   1/1     Running   0          32s

The Database Service will attempt to enable IAM authentication and configure IAM access policies for the registered databases. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.

Step 5/6. Create a 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 the user alice on your database engine. In the next step, we will authenticate to the database as the alice user via the user's Teleport account.

CREATE USER alice;
GRANT rds_iam TO alice;

CREATE USER alice IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';

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

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

Step 6/6. Connect

Once the Database Service has started and joined the cluster, log in as the alice user you created earlier to see the registered databases:

tsh login --proxy=example.teleport.sh:443 --user=alice
tsh db ls
Name                           Description                                   Labels
------------------------------ --------------------------------------------- --------
postgres-rds                   RDS instance in us-west-1                     ...
aurora-mysql                   Aurora cluster in us-west-1                   ...
aurora-mysql-custom-myendpoint Aurora cluster in us-west-1 (custom endpoint) ...
aurora-mysql-reader            Aurora cluster in us-west-1 (reader endpoint) ...

Retrieve credentials for a database and connect to it as the alice user, assigning postgres-rds to the name of a database resource listed by tsh db ls:

tsh db connect postgres-rds --db-user=alice

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

tsh db connect --db-user=postgres --db-name=postgres postgres-rds

Log out of the database and remove credentials:

tsh db logout postgres-rds

Troubleshooting

Certificate error

If your tsh db connect error includes the following text, you likely have an RDS database created before July 28, 2020, which presents an X.509 certificate that is incompatible with Teleport:

x509: certificate relies on legacy Common Name field, use SANs instead

AWS provides instructions to rotate your SSL/TLS certificate.

No credential providers error

If you see the error NoCredentialProviders: no valid providers in chain in Database Service logs then Teleport is not detecting the required credentials to connect via AWS IAM permissions. Check whether the credentials or security role has been applied in the machine running the Teleport Database Service.

Timeout errors

The Teleport Database Service needs connectivity to your database endpoints. That may require enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc program you can verify connections to databases:

nc -zv postgres-instance-1.sadas.us-east-1.rds.amazonaws.com 5432
Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!

Maximum policy size exceeded errors

Due to IAM and STS character limits, you may encounter one of the following errors in the Database Service logs when large numbers of databases are registered:

• LimitExceeded: Maximum policy size of 2048 bytes exceeded for user <iam-user>
• LimitExceeded: Maximum policy size of 10240 bytes exceeded for role <iam-role>

For reference, a user policy can maintain permissions for approximately 6 Redshift databases, or 20 RDS databases due to the IAM policy character limits. A role policy can maintain permissions for approximately 30 Redshift databases, or 100 RDS databases.

To get around this limit, try using one or a combination of the following methods:

discovery_service:
  enabled: "yes"
  aws:
    - types: ["rds"]
      regions: ["us-west-1", "us-west-2"]
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-discovery"
      tags:
        "env": "prod"

    - types: ["redshift", "redshift-serverless"]
      regions: ["us-west-2"]
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
      tags:
        "env": "dev"

db_service:
  enabled: "yes"
  resources:
    # Matches us-west-1 env=prod RDS databases from Discovery Service, and
    # overwrites assume_role_arn.
    - labels:
        "env": "prod"
        "region": "us-west-1"
      aws:
        assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-us-west-1-access"

    # Matches us-west-2 env=prod RDS databases from Discovery Service, and
    # overwrites assume_role_arn.
    - labels:
        "env": "prod"
        "region": "us-west-2"
      aws:
        assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod-us-west-2-access"

    # Matches env=dev Redshift databases from Discovery Service and inherits
    # "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
    - labels:
        "env": "dev"

teleport db configure aws create-iam --types redshift,redshift-serverless --name teleport-redshift-access
teleport db configure aws print-iam --types redshift,redshift-serverless

db_service:
  enabled: "yes"
  aws:
    - types: ["rds"]
      regions: ["us-west-1", "us-west-2"]
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-rds-env-prod"
      tags:
        "env": "prod"

    - types: ["redshift", "redshift-serverless"]
      regions: ["us-west-2"]
      assume_role_arn: "arn:aws:iam::123456789012:role/example-role-redshift-env-dev"
      tags:
        "env": "dev"

teleport db configure bootstrap \    -c /etc/teleport.yaml \    --policy-name teleport-policy-rds-env-prod \    --attach-to-role "arn:aws:iam::123456789012:role/example-role-rds-env-prod"

db_service:
  enabled: "yes"
  databases:
  - name: "rds-postgres"
    protocol: "postgres"
    uri: "rds-postgres.abcdef012345.us-west-1.rds.amazonaws.com:5432"
    aws:
        assume_role_arn: "arn:aws:iam::123456789012:role/example-rds-access-role"

teleport db configure bootstrap \    -c /etc/teleport.yaml \    --policy-name teleport-policy-rds-access \    --attach-to-role "arn:aws:iam::123456789012:role/example-rds-access-role"

kind: db
version: v3
metadata:
  name: "rds-postgres"
  labels:
    env: "dev"
spec:
  protocol: "postgres"
  uri: "rds-postgres.abcdef012345.us-west-1.rds.amazonaws.com:5432"
  aws:
    assume_role_arn: "arn:aws:iam::123456789012:role/example-rds-access-role"

db_service:
  enabled: "yes"
  resources:
    # Matches env=dev databases and overwrites assume_role_arn.
    - labels:
        "env": "dev"
      aws:
        assume_role_arn: "arn:aws:iam::123456789012:role/example-env-dev-access"

    # Matches env=prod database, and use the assume_role_arn in the database's
    # definition or use the host IAM identity if assume_role_arn is empty.
    - labels:
        "env": "prod"

teleport db configure aws create-iam --types rds --name teleport-rds-access
teleport db configure aws print-iam --types rds

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rds-db:connect",
            "Resource": "*"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "redshift:GetClusterCredentials",
            "Resource": "*"
        }
    ]
}

Next steps

• Learn how to restrict access to certain users and databases.

• Learn more about dynamic database registration.

• View the High Availability (HA) guide.

• See the YAML configuration reference for updating dynamic resource matchers or static database definitions.

• Take a look at the full CLI reference.

• Set up automatic database user provisioning.