Database Access with AWS ElastiCache and AWS MemoryDB for Redis

Teleport can provide secure access to Amazon ElastiCache or MemoryDB for Redis 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 ElastiCache or MemoryDB for Redis database with IAM authentication.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

How it works

The Teleport Database Service proxies traffic from users to AWS ElastiCache or MemoryDB for Redis. Authentication between the Database Service and the AWS-hosted Redis database can take one of two forms:

• IAM authentication (preferred): The Teleport Database Service connects to the database using a short-lived AWS IAM authentication token. AWS IAM authentication is available for ElastiCache and MemoryDB with Redis version 7.0 or above.
• Managing users: The Teleport Database Service manages users in a Redis access control list, rotates their passwords every 15 minutes, and saves these passwords in AWS Secrets Manager. The Database Service automatically sends an AUTH command with the saved password when connecting the client to the Redis server.

• Self-Hosted
• Teleport Cloud

This guide shows how to register a single Amazon Elasticache or MemoryDB cluster with your Teleport cluster. For a more scalable approach, learn how to set up Database Auto-Discovery to automatically enroll all AWS databases in your infrastructure.

Prerequisites

• A running Teleport cluster version 15.4.22 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.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• AWS account with at least one ElastiCache or MemoryDB for Redis cluster. In-transit encryption via (TLS) must be enabled.
• Permissions to create and attach IAM policies.
• redis-cli version 6.2 or newer installed and added to your system's PATH environment variable.
• A host, e.g., an EC2 instance, where you will run the Teleport Database Service.
• Redis ACL enabled for your ElastiCache or MemoryDB for Redis cluster.
• A running Teleport Discovery Service if you plan to use Database Auto-Discovery.
• 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. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  15.4.22
  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.

Step 1/6. Create a Teleport user

tctl users add \  --roles=access \  --db-users="*" \  --db-names="*" \  alice

tctl users add \  --roles=access,requester \  --db-users="*" \  --db-names="*" \  alice

For more detailed information about database access controls and how to restrict access see RBAC documentation.

Step 2/6. Create a Database Service configuration

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 Teleport on your Linux server:

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

   Edition	Value
   Teleport Enterprise Cloud	cloud
   Teleport Enterprise (Self-Hosted)	enterprise
   Teleport Community Edition	oss

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.22.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 the Database Service configuration:

ELASTICACHE_URI=""
sudo teleport db configure create \   -o file \   --name="elasticache" \   --proxy=example.teleport.sh:443 \   --protocol="redis" \   --uri=${ELASTICACHE_URI?} \   --token=/tmp/token

MEMORYDB_URI=""
sudo teleport db configure create \   -o file \   --name="memorydb" \   --proxy=example.teleport.sh:443 \   --protocol="redis" \ \   --uri=${MEMORYDB_URI} \   --token=/tmp/token

The command will generate a Database Service configuration and place it at the /etc/teleport.yaml location.

Step 3/6. Create an IAM policy for Teleport

Teleport needs AWS IAM permissions to be able to:

• Modify ElastiCache and MemoryDB user passwords for Teleport-managed users.
• Save user passwords in AWS Secrets Manager for Teleport-managed users.
• Connect to an ElastiCache or MemoryDB cluster using IAM auth.

Before you can generate IAM permissions, you must provide the Teleport Database Service access to AWS credentials.

Grant the Database Service access to credentials that it can use to authenticate to AWS. If you are running the Database Service on an EC2 instance, you may 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>

Teleport can bootstrap IAM permissions for the Database Service based on its configuration using the teleport db configure bootstrap command. You can use this command in automatic or manual mode:

• In automatic mode, Teleport will attempt to create appropriate IAM policies and attach them to the specified IAM identity role. This requires IAM permissions to create and attach IAM policies.
• In manual mode, Teleport will print required IAM policies. You can then create and attach them manually using the AWS management console.

teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole

teleport db configure bootstrap -c /etc/teleport.yaml --manual --attach-to-role arn:aws:iam::123456789012:role/TeleportRole

Step 4/6. Start the Database Service

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

sudo systemctl enable teleport
sudo systemctl 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 Database Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 5/6. Configure authentication for ElastiCache or MemoryDB users

Configure authentication for your AWS-hosted Redis database. The steps to follow depend on whether you want to enable the Teleport Database Service to use IAM authentication with ElastiCache, IAM authentication with MemoryDB, or authentication based on managing passwords via AWS Secrets Manager:

• ElastiCache IAM user
• MemoryDB IAM user
• Teleport-managed user

To enable Redis ACL, please see Authenticating users with Role-Based Access Control for ElastiCache.

Some additional limitations apply when using IAM authentication - for more information, see: ElastiCache Auth IAM Limits.

There are a few requirements for configuring an ElastiCache IAM-enabled user:

• the user must have identical username and user id properties.
• the user must have authentication mode set to "IAM".
• the user must be attached to an ElastiCache user group.

Create an ElastiCache IAM-enabled user. The following example creates an ElastiCache user with the access string on ~* +@all that represents an active user with access to all available keys and commands:

aws elasticache create-user \  --user-name iam-user-01 \  --user-id iam-user-01 \  --authentication-mode Type=iam \  --engine redis \  --access-string "on ~* +@all"

Access Strings

You may prefer a less permissive access string for your ElastiCache users. For more information about ElastiCache access strings, please see: ElastiCache Cluster RBAC Access String.

Create an ElastiCache user group and attach it to your ElastiCache replication group:

aws elasticache create-user-group \  --user-group-id iam-user-group-01 \  --engine redis \  --user-ids default iam-user-01
aws elasticache modify-replication-group \  --replication-group-id replication-group-01 \  --user-group-ids-to-add iam-user-group-01

Once the ElastiCache user has been created, verify that the user is configured to satisfy the requirements for IAM authentication:

It is highly recommended to use a different ACL than the preset open-access ACL which allows all access using the default user.

If you do not have another MemoryDB ACL yet, create one:

aws memorydb create-acl --acl-name my-acl

Make sure the ACL is attached to your MemoryDB cluster:

aws memorydb update-cluster --cluster-name my-memorydb --acl-name my-acl

Now create an MemoryDB IAM-enabled user:

aws memorydb create-user \  --user-name iam-user-01 \  --authentication-mode Type=iam \  --access-string "on ~* +@all"

Access Strings

The above example creates a MemoryDB user with the access string on ~* +@all that represents an active user with access to all available keys and commands.

You may prefer a less permissive access string for your MemoryDB users. For more information about access strings, please see: Specifying Permissions Using an Access String.

Then add this user to the ACL attached to your MemoryDB cluster:

aws memorydb update-acl --user-names-to-add iam-user-01 --acl-name my-acl

To enable Redis ACL, please see Authenticating users with Role-Based Access Control for ElastiCache and Authenticating users with Access Control Lists for MemoryDB.

Once an ElastiCache or MemoryDB user is created with the desired access, add an AWS resource tag teleport.dev/managed with the value true to this user:

The Database Service will automatically discover this user if it is associated with a registered database. Keep in mind that it may take the Database Service some time (up to 20 minutes) to discover this user once the tag is added.

If you choose not to use the above options, Teleport will not automatically authenticate with the Redis server.

You can either set up a "no password" configuration for your ElastiCache or MemoryDB user, or manually enter an AUTH command with the password you have configured after a successful client connection. However, it is strongly advised to use one of the first two options or a strong password for better security.

Step 6/6. Connect

Once the Database Service has started and joined the cluster, log in to see the registered databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name                        Description                                               Labels
--------------------------- --------------------------------------------------------- --------
my-cluster-mode-elasticache                                                           ...
my-elasticache                                                                        ...
my-elasticache-reader                                                                 ...
my-memorydb                                                                           ...

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
Name                        Description                                               Labels
--------------------------- --------------------------------------------------------- --------
my-cluster-mode-elasticache                                                           ...
my-elasticache                                                                        ...
my-elasticache-reader                                                                 ...
my-memorydb                                                                           ...

To retrieve credentials for a database and connect to it:

tsh db connect --db-user=my-database-user my-elasticache

If flag --db-user is not provided, Teleport logs in as the default user.

Now, depending on the authentication configurations, you may need to send an AUTH command to authenticate with the Redis server:

AUTH my-database-user <USER_PASSWORD>

AUTH <SHARED_AUTH_TOKEN>

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout my-elasticache
Remove credentials for all database instances.
tsh db logout

Troubleshooting

Certificate error

If your tsh db connect error includes the following text, you likely have an RDS database created before July 28, 2020, which presents an X.509 certificate that is incompatible with Teleport:

x509: certificate relies on legacy Common Name field, use SANs instead

AWS provides instructions to rotate your SSL/TLS certificate.

No credential providers error

If you see the error NoCredentialProviders: no valid providers in chain in Database Service logs then Teleport is not detecting the required credentials to connect via AWS IAM permissions. Check whether the credentials or security role has been applied in the machine running the Teleport Database Service.

When running on EKS, this error may occur if the Teleport Database Service cannot access IMDSv2 when the PUT requests hop limit on the worker node instance is set to 1. You can use the following commands to check the hop limit:

aws ec2 describe-instances --instance-ids <node-instance-id> | grep HttpPutResponseHopLimit
                        "HttpPutResponseHopLimit": 1,

See IMDSv2 support for EKS and EKS best practices for more details.

Timeout errors

The Teleport Database Service needs connectivity to your database endpoints. That may require enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc program you can verify connections to databases:

nc -zv postgres-instance-1.sadas.us-east-1.rds.amazonaws.com 5432
Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!

Not authorized to perform sts:AssumeRole

The Database Service assumes an IAM role in one of following situations:

• An IAM role is used as db_user when accessing AWS services that require IAM roles as database users, such as DynamoDB, Keyspaces, Opensearch, and Redshift Serverless.
• The assume_role_arn field is specified for the database resources or dynamic resource matchers.

You may encounter the following error if the trust relationship is not configured properly between the IAM roles:

AccessDenied: User: arn:aws:sts::111111111111:assumed-role/database-service-role/i-* is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::111111111111:role/database-user-role

To allow IAM Role role1 to assume IAM Role role2, the following is generally required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::aws-account-id:role/role1"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::aws-account-id:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::external-aws-account-id:role/role1"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "example-external-id"
        }
      }
    }
  ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "arn:aws:iam::aws-account-id:role/role2"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

You can test the trust relationship by running this AWS CLI command as role1:

aws sts assume-role --role-arn arn:aws:iam::111111111111:role/role2 --role-session-name test-trust-relationship

Learn more on how to use trust policies with IAM roles.

Next steps

• Learn how to restrict access to certain users and databases.

• View the High Availability (HA) guide.

• Take a look at the YAML configuration reference.

• See the full CLI reference.