
Access to AWS DynamoDB can be provided by Teleport Database Access. This allows for fine-grain access control through Teleport's RBAC.
This guide will help you to:
- Install the Teleport Database Service.
- Set up the Teleport Database Service to access DynamoDB.
- Connect to your DynamoDB databases through the Teleport Database Service.

Prerequisites
- AWS account with DynamoDB databases.
- IAM permissions to create IAM roles.
aws
Command Line Interface (CLI) tool installed in$PATH
.
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- A host, e.g., an EC2 instance, where you will run the Teleport Database Service. This guide assumes an EC2 instance when creating and applying IAM roles, and must be adjusted accordingly for custom configurations.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.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 statusCluster myinstance.teleport.sh
Version 12.1.2
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
This guide provides an example configuration of IAM access roles as a model, and uses an EC2 instance to serve the Teleport Database Service. The level of access provided may not suit your needs, or may not fit your organization's access conventions. You should adjust the AWS IAM permissions to fit your needs.
Step 1/4. Create IAM roles for DynamoDB access
The setup described in this guide requires two IAM roles:
- One associated with the EC2 instance running the Teleport Database Access service, which lets it assume additional roles granted to the user.
- One that can be assumed by the EC2 instance role and grants access to DynamoDB services to users.
EC2 instance role
Visit the IAM > Roles page of the AWS Console, then press "Create Role". Under Trusted entity type select "AWS service". Under Use case select "EC2", then click Next.

On the "Add Permissions" page, you can simply click Next since this role does not require any permissions. In this guide, we will use the example name TeleportDatabaseService
for this role. Once you have chosen a name, click Create Role to complete the process.
DynamoDB access role
Navigate back to the Roles page and create a new role. Select the "AWS account" option, which creates a default trust policy to allow other entities in this account to assume this role:

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

The AmazonDynamoDBFullAccess
policy may grant more permissions than desired.
If you want to use a different IAM policy to reduce permissions, refer to
Managing access permissions to your Amazon DynamoDB
Resources
for more information.
Click Next. On the next page, enter a role name. In this guide we'll use
the example name ExampleTeleportDynamoDBRole
for this role.
Under "Select trusted entities", update the JSON to allow the TeleportDatabaseService
role to assume this role:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::abcd1234-this-is-an-example:role/TeleportDatabaseService"
]
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
Finally, click Create Role.
Step 2/4. Configure the Teleport IAM role mapping
The next step is to give your Teleport users permissions to assume AWS IAM roles when accessing AWS resources through your Teleport cluster.
You can do this by creating a Teleport role with the db_users
field
listing the IAM role ARN created in the previous step. Create a file called
aws-dynamodb-access.yaml
with the following content:
kind: role
version: v6
metadata:
name: aws-dynamodb-access
spec:
allow:
db_labels:
'*': '*'
db_users:
- 'ExampleTeleportDynamoDBRole'
Create the new role:
tctl create -f aws-dynamodb-access.yaml
Assign the aws-dynamodb-access
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding aws-dynamodb-access
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - aws-dynamodb-access
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding aws-dynamodb-access
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - aws-dynamodb-access
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding aws-dynamodb-access
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - aws-dynamodb-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding aws-dynamodb-access
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - aws-dynamodb-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
Step 3/4. Install the Teleport Database Service
Create an EC2 instance to host the Teleport Database Service, and attach the
TeleportDatabaseService
AWS IAM role to it. If you're hosting the service another
way, you must provide AWS credentials to the service - see AWS credentials
configuration
for more details.
For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China
regions, please set the corresponding region in the AWS_REGION
environment
variable or in the AWS credentials file so that the Database Service can use
the correct STS endpoint.
Generate a token
For users with a lot of infrastructure in AWS, or who might create or recreate many instances, consider alternative methods for joining new EC2 instances running Teleport:
A join token is required to authorize a Teleport Database Service instance to join the cluster. Generate a short-lived join token and save the output of the command:
tctl tokens add \ --type=db \ --db-name=example-dynamodb \ --db-protocol=dynamodb
Use the token provided by the output of this command in the next step.
Install and start Teleport
Install Teleport on the host where you will run the Teleport Database Service. See our Installation page for options besides Linux servers.
Use the appropriate commands for your environment to install your package.
Teleport Edition
Add the Teleport repository to your repository list:
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v12. 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/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v12. 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/v12/teleport.repo")sudo yum install teleportTip: 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
Optional: Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleportsudo ./install
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
After Downloading the .deb
file for your system architecture, install it with
dpkg
. The example below assumes the root
user:
dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.debSelecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...
After Downloading the .rpm
file for your system architecture, install it with rpm
:
rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpmwarning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
Create a file called /etc/teleport.yaml
with the following content:
version: v3
teleport:
nodename: CHANGEME
data_dir: /var/lib/teleport
proxy_server: teleport.example.com:443
auth_token: abcd123-insecure-do-not-use-this
db_service:
enabled: "yes"
resources:
- labels:
"*": "*"
# Lists statically registered databases proxied by this agent.
databases:
- name: "example-dynamodb"
protocol: "dynamodb"
# optional uri, if uri is set then AWS region can be extracted from it
# or if AWS region is already set then the regions must match.
# uri: "dynamodb.us-east-1.amazonaws.com:443"
static_labels:
env: "dev"
aws:
region: "us-east-1"
account_id: "abcd1234-this-is-an-example"
Substitute teleport.example.com
with the address of your Teleport Proxy Service.
(For Teleport Cloud customers, this will be similar to mytenant.teleport.sh
.)
Replace the value of auth_token
with the token generated in the previous step.
Now start the Teleport Database Service:
sudo systemctl start teleport
sudo teleport install systemd --output=/etc/systemd/system/teleport.service;sudo systemctl enable teleportsudo systemctl start teleport
Step 4/4 Connect
Once the Database Service has started and joined the cluster, you can start connecting to your DynamoDB database.
Create a proxy tunnel:
tsh proxy db --tunnel --port 8000 --db-user=ExampleTeleportDynamoDBRole example-dynamodb
You can test the connection to the database through the aws
CLI:
aws dynamodb list-tables --endpoint-url=http://localhost:8000{
"TableNames": [
"table1",
"table2",
"table3"
]
}
You can also connect to this database from the AWS NoSQL Workbench, as documented in our Database Access GUI Clients guide.
You can also use this tunnel for programmatic access. The example below uses the boto3
SDK from AWS:
$ python3
Python 3.10.4 (main, Mar 31 2022, 03:37:37) [Clang 12.0.0 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import boto3
>>> clt = boto3.client('dynamodb', endpoint_url='http://localhost:8000')
>>> res = clt.list_tables()
>>> print(res)
{'TableNames': *snip output*}
>>>
Next Steps
- See Dynamic Database Registration to learn how to use resource labels to keep Teleport up to date with accessible databases in your infrastructure.