
Access to AWS DynamoDB can be provided by Teleport Application Access for the AWS Console and API. This is an alternative to accessing DynamoDB through the Teleport Database service, as described in our Database Access with AWS DynamoDB guide.
Note that using the Database Service will allow you to connect with GUI clients, whereas the Application Service does not. On the other hand, a single Application Service configuration can access DynamoDB across regions, while Database resources must be configured for each region with DynamoDB databases.
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 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.
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.
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
.)
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 (or CNAME for services that only provide a hostname) record exists for each
application-specific subdomain so clients can access your applications via Teleport.
You should create either a separate DNS 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":

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. Create a file called
aws-dynamodb-access.yaml
with the following content:
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.
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/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
On the host where you will run the Teleport Application Service, copy the token
to a file called /tmp/token
.
Replace https://console.aws.amazon.com
with
https://console.amazonaws-us-gov.com
for AWS GovCloud (US) regions or
https://console.amazonaws.cn
for AWS China regions.
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.
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.
Edit the Teleport configuration file (/etc/teleport.yaml
) to include the
following information, adjusting the value of proxy_server
to specify the host
and port of your Teleport Proxy Service:
version: v3
teleport:
join_params:
token_name: "/tmp/token"
method: token
proxy_server: "teleport.example.com:443"
auth_service:
enabled: off
proxy_service:
enabled: off
ssh_service:
enabled: off
app_service:
enabled: true
apps:
- name: aws-dynamodb
uri: https://console.aws.amazon.com/dynamodbv2/home
Grant the Teleport Application Service access to credentials that it can use to authenticate to AWS. If you are running the Teleport Application Service on an EC2 instance, you should use the EC2 Instance Metadata Service method. Otherwise, you must use environment variables:
Teleport will detect when it is running on an EC2 instance and use the Instance Metadata Service to fetch credentials.
Teleport's built-in AWS client reads credentials from the following environment variables:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION
When you start the Teleport Application Service, the service reads environment variables from a
file at the path /etc/default/teleport
. Obtain these credentials from your
organization. Ensure that /etc/default/teleport
has the following content,
replacing the values of each variable:
AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>
Teleport's AWS client loads credentials from different sources in the following order:
- Environment Variables
- Shared credentials file
- Shared configuration file (Teleport always enables shared configuration)
- EC2 Instance Metadata (credentials only)
While you can provide AWS credentials via a shared credentials file or shared
configuration file, you will need to run the Teleport Application Service with the AWS_PROFILE
environment variable assigned to the name of your profile of choice.
If you have a specific use case that the instructions above do not account for, consult the documentation for the AWS SDK for Go for a detailed description of credential loading behavior.
Configure the Teleport Application Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Application Service.
On the host where you will run the Teleport Application Service, start Teleport:
sudo systemctl start teleport
On the host where you will run the Teleport Application Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
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 Application Service can use
the correct STS endpoint.
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": "*"
}
]
}
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 apps login --aws-role ExampleTeleportDynamoDBRole aws-dynamodbLogged 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 apps logout aws-dynamodb
Using other DynamoDB applications
First, log into the previously configured AWS DynamoDB app if you haven't already done so:
tsh apps 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 23456Started 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=abcd1234-this-is-an-example
AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
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=abcd1234-this-is-an-exampleexport AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-exampleexport AWS_CA_BUNDLE=<ca-bundle-path>export HTTPS_PROXY=http://127.0.0.1:23456python3>>> 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 23457Started 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=abcd1234-this-is-an-example
AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
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=abcd1234-this-is-an-exampleexport AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-exampleexport NODE_EXTRA_CA_CERTS=<ca-bundle-path>export DYNAMO_ENDPOINT=https://127.0.0.1:23457dynamodb-admindatabase 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 apps logout aws-dynamodb
Next steps
- More information on AWS Management and API with Teleport Application Access.
- Learn more about AWS service endpoints.