Teleport

Database Access with AWS DynamoDB

OpenSource
Enterprise
Cloud

Improve

Access to AWS DynamoDB is provided by Teleport Application Access for the AWS Console and API.

This guide will help you to:

Install the Teleport Application Service.
Set up the Teleport Application Service to access the AWS Console and API.
Connect to your DynamoDB databases through the Teleport Application Service.

Prerequisites

AWS account with DynamoDB databases.
IAM permissions to create IAM roles.
aws Command Line Interface (CLI) tool installed in PATH.
A host, e.g., an EC2 instance, where you will run the Teleport Application Service.

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 10.3.1.
```
tctl version
Teleport v10.3.1 go1.18
tsh version
Teleport v10.3.1 go1.18
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 10.3.1, which you can download by visiting the customer portal.
```
tctl version
Teleport v10.3.1 go1.18
tsh version
Teleport v10.3.1 go1.18
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 10.2.2. To download these tools, visit the Downloads page.
```
tctl version
Teleport v10.2.2 go1.18
tsh version
Teleport v10.2.2 go1.18
```

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

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

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  10.2.2
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Not yet a Teleport user?

If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our getting started guides or try our Teleport Application Access interactive learning track.

We will assume your Teleport cluster is accessible at teleport.example.com and *.teleport.example.com. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to mytenant.teleport.sh.)

Application Access and DNS

Teleport assigns a subdomain to each application you have configured for Application Access (e.g., grafana.teleport.example.com), so you will need to ensure that a DNS A record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS A record for each subdomain or a single record with a wildcard subdomain such as *.teleport.example.com. This way, your certificate authority (e.g., Let's Encrypt) can issue a certificate for each subdomain, enabling clients to verify your Teleport hosts regardless of the application they are accessing.

Step 1/5. Create an IAM role for DynamoDB access

Visit the Roles page of the AWS Console, then press "Create Role".

Select the "AWS account" option, which creates a default trust policy to allow other entities in this account to assume this role:

Press "Next". Find the AWS-managed policy AmazonDynamoDBFullAccess and then select the policy:

Press "Next". Enter a role name and press "Create role":

Apply least-privilege permissions

AmazonDynamoDBFullAccess may provide too much access for your intentions. To use a different IAM policy to reduce permissions, see Managing access permissions to your Amazon DynamoDB Resources for more details.

Step 2/5. Configure the Teleport IAM role mapping

The next step is to give your Teleport users permissions to assume IAM roles in your Teleport cluster.

You can do this by creating a Teleport role with the aws_role_arns field listing the IAM role ARN created in the previous step:

kind: role
version: v5
metadata:
  name: aws-dynamodb-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns:
    - arn:aws:iam::123456789000:role/ExampleTeleportDynamoDBRole

The aws_role_arns field supports template variables so they can be populated dynamically based on your users' identity provider attributes. See Role Templates for details.

Now assign this role to the Teleport users you wish to grant access to DynamoDB.

Step 3/5. Install the Teleport Application Service

Generate a token

A join token is required to authorize a Teleport Application Service instance to join the cluster. Generate a short-lived join token and save the output of the command:

tctl tokens add \    --type=app \    --app-name=aws-dynamodb \    --app-uri=https://console.aws.amazon.com/dynamodbv2/home

The output should contain a teleport app start command that can be used to start the Teleport Application Service in the next step.

Install and start Teleport

Install Teleport on the host where you will run the Teleport Application Service. See our Installation page for options besides Linux servers.

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 v10. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \  https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v10" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v10. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v10/teleport.repo")
sudo yum install teleport

curl https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v10.3.1-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v10.3.1-linux-arm-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v10.3.1-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Using this APT repo may result in breaking upgrades upon "apt upgrade" as all major versions will be
published under the same component. We recommend following the instructions in the
"Debian/Ubuntu (DEB)" tab instead.
Download Teleport's PGP public key
sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \  -o /usr/share/keyrings/teleport-archive-keyring.asc
Add the Teleport APT repository
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport
Optional:  Using DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

Now start the Teleport Application Service using the output from the previous step:

teleport app start \   --token=abcd123-insecure-do-not-use-this \   --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \   --auth-server=https://teleport.example.com:443 \   --name=aws-dynamodb \   --uri=https://console.aws.amazon.com/dynamodbv2/home

Step 4/5. Give Teleport permissions to assume roles

Next, attach the following policy to the IAM role or IAM user the Teleport Application Service instance is using, which allows the Application Service to assume the IAM roles:

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

Tip

You can make the policy more strict by providing specific IAM role resource ARNs in the "Resource" field instead of using a wildcard.

Step 5/5. Connect

Once the Application Service has started and joined the cluster, you can start connecting to your DynamoDB database.

Using AWS Management Console

First log in to the Teleport Web UI at https://teleport.example.com (replace with your Proxy Service's public address).

Navigate to the Applications tab in your Teleport cluster's control panel and click on the Launch button for the AWS DynamoDB application. This will bring up an IAM role selector:

Click on the role you want to assume and you will get redirected to the AWS Management Console, signed in with the selected role.

In the console's top-right corner you should see that you're logged in through federated login and the name of your assumed IAM role:

Note that your federated login session is marked with your Teleport username.

Using AWS CLI

Now, log into the previously configured AWS DynamoDB app on your desktop:

tsh app login --aws-role ExampleTeleportDynamoDBRole aws-dynamodb
Logged into AWS app aws. Example AWS CLI command:
tsh aws s3 ls

The --aws-role flag allows you to specify the AWS IAM role to assume when accessing the AWS API. You can either provide a role name like --aws-role ExampleTeleportDynamoDBRole or a full role ARN like arn:aws:iam::123456789000:role/ExampleTeleportDynamoDBRole.

Now you can use the tsh aws command like the native aws command-line tool:

tsh aws dynamodb list-tables

To log out of the aws-dynamodb application and remove credentials:

tsh app logout aws-dynamodb

Using other DynamoDB applications

First, log into the previously configured AWS DynamoDB app if you haven't already done so:

tsh app login --aws-role ExampleTeleportDynamoDBRole aws-dynamodb

To connect your DynamoDB application, you can start either a local HTTPS proxy or a local AWS Service Endpoint proxy.

By default, starting the AWS app proxy creates a local HTTPS proxy server that forwards AWS requests to the Teleport Proxy Service, enabling you to access AWS applications.

Now, use the following command to start the proxy your applications will be connecting to:

tsh proxy aws -p 23456
Started AWS proxy on http://127.0.0.1:23456.
Use the following credentials and HTTPS proxy setting to connect to the proxy:
  AWS_ACCESS_KEY_ID=<access-key-id>
  AWS_SECRET_ACCESS_KEY=<secret-access-key>
  AWS_CA_BUNDLE=<ca-bundle-path>
  HTTPS_PROXY=http://127.0.0.1:23456

Use the displayed AWS credentials and HTTPS proxy settings when configuring your application.

For example, you can assign the AWS credentials and the HTTPS proxy address to environment variables for Python AWS SDK:

export AWS_ACCESS_KEY_ID=<access-key-id>
export AWS_SECRET_ACCESS_KEY=<secret-access-key>
export AWS_CA_BUNDLE=<ca-bundle-path>
export HTTPS_PROXY=http://127.0.0.1:23456
python3
>>> import boto3
>>> boto3.client('dynamodb').list_tables()
{'TableNames': ['my-dynamodb-table'], 'ResponseMetadata': {...}}

If your application cannot use a HTTPS proxy, start the AWS app proxy with the --endpoint-url flag to create a local server that can be used as an AWS Service Endpoint.

tsh proxy aws --endpoint-url -p 23457
Started AWS proxy which serves as an AWS endpoint URL at https://localhost:23457
In addition to the endpoint URL, use the following credentials to connect to the proxy:
  AWS_ACCESS_KEY_ID=<access-key-id>
  AWS_SECRET_ACCESS_KEY=<secret-access-key>
  AWS_CA_BUNDLE=<ca-bundle-path>

For example, to connect the GUI tool dynamodb-admin to the local AWS Service Endpoint proxy:

export AWS_ACCESS_KEY_ID=<access-key-id>
export AWS_SECRET_ACCESS_KEY=<secret-access-key>
export NODE_EXTRA_CA_CERTS=<ca-bundle-path>
export DYNAMO_ENDPOINT=https://127.0.0.1:23457
dynamodb-admin
database endpoint:     https://127.0.0.1:23457
region:                ca-central-1
accessKey:             <access-key-id>
dynamodb-admin listening on http://localhost:8001 (alternatively http://0.0.0.0:8001)

To log out of the aws-dynamodb application and remove credentials:

tsh app logout aws-dynamodb

Next steps

More information on AWS Management and API with Teleport Application Access.
Learn more about AWS service endpoints.

Have a suggestion or can’t find something?

IMPROVE THE DOCS