AWS DynamoDB using the Teleport Application Service

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.

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

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

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.)

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":

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

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:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

  roles:
   - access
   - auditor
   - editor
+  - aws-dynamodb-access

tctl create -f out.yaml

tctl get github/github --with-secrets > github.yaml

  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - aws-dynamodb-access

tctl create -f github.yaml

tctl get --with-secrets saml/mysaml > saml.yaml

  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - aws-dynamodb-access

tctl create -f saml.yaml

tctl get oidc/myoidc --with-secrets > oidc.yaml

  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - aws-dynamodb-access

tctl create -f saml.yaml

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.

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.

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 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/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 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 teleport
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
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

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.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting 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 ...

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: 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.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

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.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

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:

AWS_ACCESS_KEY_ID=00000000000000000000
AWS_SECRET_ACCESS_KEY=0000000000000000000000000000000000000000
AWS_DEFAULT_REGION=<YOUR_REGION>

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.

sudo systemctl start teleport

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

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": "*"
    }
  ]
}

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-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 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.

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=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

export AWS_ACCESS_KEY_ID=abcd1234-this-is-an-example
export AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
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': {...}}

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=abcd1234-this-is-an-example
  AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
  AWS_CA_BUNDLE=<ca-bundle-path>

export AWS_ACCESS_KEY_ID=abcd1234-this-is-an-example
export AWS_SECRET_ACCESS_KEY=zyxw9876-this-is-an-example
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 apps logout aws-dynamodb

Next steps

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