Skip to main content
Version: 17.x (unreleased)

Database Access with Amazon DynamoDB

Teleport can provide secure access to Amazon DynamoDB via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.

In this guide, you will:

  1. Configure your Amazon DynamoDB database with IAM authentication.
  2. Add the database to your Teleport cluster.
  3. Connect to the database via Teleport.

How it works​

Teleport users connect to DynamoDB using a local proxy server that forwards requests to the Teleport Database Service via the Teleport Proxy Service. When connecting, the user chooses an IAM role to assume. The Teleport Database Service has permissions to assume this role and potentially other IAM roles. When the Teleport Database Service receives a user request, it rewrites the request with credentials from AWS, then forwards it to the DynamoDB API.

DynamoDB Self-Hosted

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 version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • 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 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: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  17.0.0-dev
    # 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.

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

Create Role to Identify EC2 Instance

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:

Create Role Step 1

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

Create Role Step 2

Apply least-privilege permissions

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: v7
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 appropriate commands for your authentication provider:

  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.

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.

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 Database Service can use the correct STS endpoint.

Generate a token​

Alternative methods

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:

The Database Service requires a valid join token to join your Teleport cluster. Run the following tctl command and save the token output in /tmp/token on the server that will run the Database Service:

$ tctl tokens add --type=db --format=text
abcd123-insecure-do-not-use-this

Install and start Teleport​

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

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

  3. Install Teleport on your Linux server:

    $ curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition

    The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

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: /tmp/token
db_service:
  enabled: "yes"
  # 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.) The token generated should have been placed in the file /tmp/token.

Configure the Teleport Database 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 Database Service.

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

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of the Teleport Database Service with systemctl status teleport and view its logs with journalctl -fu 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.