# Amazon DynamoDB using the Teleport Application Service

You can configure the Teleport Application Service to enable secure access to Amazon DynamoDB.

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.

**Self-Hosted**

![DynamoDB Self-Hosted](/docs/assets/images/dynamodb_selfhosted-51b48f71d2826f48615c95d339b34ab6.png)

**Teleport Enterprise Cloud**

![DynamoDB Cloud](/docs/assets/images/dynamodb_cloud-2146454a64e74008626b4eea0646d375.png)

## How it works

The Teleport Application Service enables secure access to DynamoDB via its [integration](https://goteleport.com/docs/enroll-resources/application-access/cloud-apis/aws-console.md) with the AWS management console and API. This is an alternative to accessing DynamoDB through the Teleport Database service, as described in our [Protect Amazon DynamoDB with Teleport](https://goteleport.com/docs/enroll-resources/database-access/enrollment/aws/aws-dynamodb.md) guide.

---

WARNING

The Application Service's integration with AWS is not designed specifically for DynamoDB, while the Database Service has a purpose-built DynamoDB integration. As a result, we recommend using the Database Service to enable secure access to DynamoDB.

It is worth noting that 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.

---

## 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. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

* The `tctl` and `tsh` clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tctl` and `tsh` clients:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

- To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  18.7.3
  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.

---

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](https://goteleport.com/docs/enroll-resources/application-access/getting-started.md) or try our Teleport application access [interactive learning track](https://goteleport.com/labs/).

---

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

---

DNS AND TELEPORT-PROTECTED APPLICATIONS

Once the Teleport Application Service is proxying traffic to your web application, the Teleport Proxy Service makes the application available at the following URL:

```
https://<APPLICATION_NAME>.<TELEPORT_DOMAIN>

```

For example, if your Teleport domain name is `teleport.example.com`, the application named `my-app` would be available at `https://my-app.teleport.example.com`. The Proxy Service must present a TLS certificate for this domain name that browsers can verify against a certificate authority.

If you are using Teleport Enterprise (Cloud), DNS records and TLS certificates for this domain name are provisioned automatically. If you are self-hosting Teleport, you must configure these yourself:

1. Create either:

   - A DNS A record that associates a wildcard subdomain of your Teleport Proxy Service domain, e.g., `*.teleport.example.com`, with the IP address of the Teleport Proxy Service.
   - A DNS CNAME record that associates a wildcard subdomain of your Proxy Service domain, e.g., `*.teleport.example.com`, with the domain name of the Teleport Proxy Service.

2. Ensure that your system provisions TLS certificates for Teleport-registered applications. The method to use depends on how you originally set up TLS for your self-hosted Teleport deployment, and is outside the scope of this guide.

   In general, the same system that provisions TLS certificates signed for the web address of the Proxy Service (e.g., `teleport.example.com`) must also provision certificates for the wildcard address used for applications (e.g., `*.teleport.example.com`).

Take care not to create DNS records that map the Teleport cluster subdomain of a registered application to the application's own host, as attempts to navigate to the application will fail.

---

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

Create an IAM role that provides access to your DynamoDB resources. Teleport Application Service will assume this IAM role on behalf of the Teleport user that accesses these DynamoDB resources.

There are several methods to create an IAM role:

**Using AWS Console**

Visit the [Roles page](https://console.aws.amazon.com/iamv2/home#/roles) 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:

![Create Role Step 1](/docs/assets/images/dynamodb-create-role-1-de95f8631ab398d51ab1f49ebf5fb258.png)

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

![Create Role Step 2](/docs/assets/images/aws-create-iam-role-2-22c5a8689a2c3c1dd243f732b25ef454.png)

Press "Next". Enter role name `ExampleTeleportDynamoDBRole` and press "Create role":

![Create Role Step 3](/docs/assets/images/aws-create-iam-role-3-f0bdaa55fb18e32354962256d0ee8386.png)

**Using AWS CLI**

Create a file with the following trust policy. Replace aws-account-id with your AWS Account ID:

```
$ cat > trust-relationship.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::aws-account-id:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF
```

Create an IAM role with name `ExampleTeleportDynamoDBRole`:

```
$ aws iam create-role --role-name ExampleTeleportDynamoDBRole --assume-role-policy-document file://trust-relationship.json
```

Attach managed policy `AmazonDynamoDBFullAccess` to the role:

```
$ aws iam attach-role-policy --role-name ExampleTeleportDynamoDBRole --policy-arn arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess
```

**Using Terraform**

Add the following resources to your Terraform deployment. Replace aws-account-id with your AWS Account ID:

```
$ cat > teleport_iam_role_ExampleTeleportDynamoDBRole.tf <<EOF
resource "aws_iam_role" "teleport-ExampleTeleportDynamoDBRole" {
  name = "ExampleTeleportDynamoDBRole"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::aws-account-id:root"
        }
        Action = "sts:AssumeRole"
      },
    ]
  })
}
resource "aws_iam_role_policy_attachment" "teleport-ExampleTeleportDynamoDBRole-AmazonDynamoDBFullAccess" {
  role       = aws_iam_role.teleport-ExampleTeleportDynamoDBRole.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"
}
EOF
```

Then `terraform apply`.

---

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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/access-control-overview.html) for more details.

---

## Step 2/5. Configure the Teleport IAM role mapping

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:

```
$ cat > aws-dynamodb-access.yaml <<EOF
kind: role
version: v5
metadata:
  name: aws-dynamodb-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns:
    - arn:aws:iam::aws-account-id:role/ExampleTeleportDynamoDBRole
EOF
```

Remember to replace aws-account-id with your AWS Account ID.

Templating "aws\_role\_arns" in role definitions

The `aws_role_arns` field supports template variables so they can be populated dynamically based on your users' identity provider attributes. Here are some examples:

**local users**

Use `{{internal.aws_role_arns}}` in the role definition:

```
kind: role
version: v5
metadata:
  name: aws-dynamodb-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns: ['{{internal.aws_role_arns}}']

```

Then specify the IAM roles through user traits:

```
kind: user
version: v2
metadata:
  name: alice
spec:
  roles: ['aws-dynamodb-access']
  traits:
    aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_alice']
---
kind: user
version: v2
metadata:
  name: bob
spec:
  roles: ['aws-dynamodb-access']
  traits:
    aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_bob']

```

**SSO users**

Let's assume that an IAM role has been created for each Teleport user, and the name of the IAM role corresponds to their Email addresses without the Email domain suffix.

Then `aws_role_arns` can be templated with `external.email`:

```
kind: role
version: v5
metadata:
  name: aws-dynamodb-access
spec:
  allow:
    app_labels:
      '*': '*'
    aws_role_arns: ['arn:aws:iam:123456789000:role/{{email.local(external.email)}}']

```

See [Role Templates](https://goteleport.com/docs/zero-trust-access/rbac-get-started/role-templates.md) for details.

Create the new role:

```
$ tctl create -f aws-dynamodb-access.yaml
```

---

TIP

You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit.

---

Assign the `aws-dynamodb-access` role to your Teleport user by running the appropriate commands for your authentication provider:

**Local User**

1. Retrieve your local user's roles as a comma-separated list:

   ```
   $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
   ```

2. Edit your local user to add the new role:

   ```
   $ tctl users update $(tsh status -f json | jq -r '.active.username') \
     --set-roles "${ROLES?},aws-dynamodb-access"
   ```

3. Sign out of the Teleport cluster and sign in again to assume the new role.

**GitHub**

1. Open your `github` authentication connector in a text editor:

   ```
   $ tctl edit github/github
   ```

2. Edit the `github` connector, adding `aws-dynamodb-access` to the `teams_to_roles` section.

   The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

   Here is an example:

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

   ```

3. Apply your changes by saving and closing the file in your editor.

4. Sign out of the Teleport cluster and sign in again to assume the new role.

**SAML**

1. Retrieve your `saml` configuration resource:

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

   Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `saml.yaml` file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

2. Edit `saml.yaml`, adding `aws-dynamodb-access` to the `attributes_to_roles` section.

   The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

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

   ```

3. Apply your changes:

   ```
   $ tctl create -f saml.yaml
   ```

4. Sign out of the Teleport cluster and sign in again to assume the new role.

**OIDC**

1. Retrieve your `oidc` configuration resource:

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

   Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `oidc.yaml` file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

2. Edit `oidc.yaml`, adding `aws-dynamodb-access` to the `claims_to_roles` section.

   The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

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

   ```

3. Apply your changes:

   ```
   $ tctl create -f oidc.yaml
   ```

4. Sign out of the Teleport cluster and sign 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 \
    --app-uri=https://console.aws.amazon.com/console/home
```

On the host where you will run the Teleport Application Service, copy the token to a file called `/tmp/token`.

---

NON-STANDARD AWS REGIONS

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](https://goteleport.com/docs/installation.md) page for options besides Linux servers.

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://).

2. Run your cluster's install script:

   ```
   $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
   ```

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: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
app_service:
  enabled: true
  apps:
  - name: aws
    uri: https://console.aws.amazon.com/console/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 may use the EC2 Instance Metadata Service method
- If you are running the Teleport Application Service in Kubernetes, you can use IAM Roles for Service Accounts (IRSA)
- Otherwise, you must use environment variables

**Instance Metadata Service**

Teleport will detect when it is running on an EC2 instance and use the Instance Metadata Service to fetch credentials.

The EC2 instance should be configured to use an EC2 instance profile. For more information, see: [Using Instance Profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html).

**Kubernetes IRSA**

Refer to [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to set up an OIDC provider in AWS and configure an AWS IAM role that allows the pod's service account to assume the role.

**Environment Variables**

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>

```

Have multiple sources of AWS credentials?

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](https://docs.aws.amazon.com/sdk-for-go/api/aws/session/) 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.

**Package Manager**

On the host where you will run the Teleport Application Service, enable and start Teleport:

```
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

**TAR Archive**

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.service
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

You can check the status of the Teleport Application Service with `systemctl status teleport` and view its logs with `journalctl -fu teleport`.

---

NON-STANDARD AWS REGIONS

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

```

---

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

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 application. This will bring up an IAM role selector:

![IAM role selector](/docs/assets/images/aws-database-select-iam-role-7f54345566f0aa287533a28265a28cfe.png)

Click on the role `ExampleTeleportDynamoDBRole` 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 is `ExampleTeleportDynamoDBRole/<teleport-username>` where the session name is your Teleport username.

### Using AWS CLI

Log into the previously configured AWS app on your desktop:

```
$ tsh apps login --aws-role ExampleTeleportDynamoDBRole aws
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` application and remove credentials:

```
$ tsh apps logout aws
```

### Using other DynamoDB applications

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

```
$ tsh apps login --aws-role ExampleTeleportDynamoDBRole aws
```

To connect your DynamoDB application, start a local HTTPS proxy that forwards AWS requests to the Teleport Proxy Service, enabling you to access AWS applications.

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

```

To log out of the `aws` application and remove credentials:

```
$ tsh apps logout aws
```

## Next steps

- More information on [protecting AWS Console with Teleport](https://goteleport.com/docs/enroll-resources/application-access/cloud-apis/aws-console.md).
- Learn more about [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html).