![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Database Access with Amazon ElastiCache and Amazon MemoryDB for Redis
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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:
- Configure your Amazon ElastiCache or MemoryDB for Redis database with IAM authentication.
- Add the database to your Teleport cluster.
- Connect to the database via Teleport.
How it works
The Teleport Database Service proxies traffic from users to Amazon 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.
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 databases in your infrastructure.
Prerequisites
-
A running Teleport cluster version 16.2.1 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- 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
version6.2
or newer installed and added to your system'sPATH
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 runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/6. Create a Teleport user
To modify an existing user to provide access to the Database Service, see Database Access Controls
Create a local Teleport user with the built-in access
role:
tctl users add \ --roles=access \ --db-users="*" \ --db-names="*" \ alice
Create a local Teleport user with the built-in access
and requester
roles:
tctl users add \ --roles=access,requester \ --db-users="*" \ --db-names="*" \ alice
Flag | Description |
---|---|
--roles | List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport. |
--db-users | List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user. |
--db-names | List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database. |
Database names are only enforced for PostgreSQL, MongoDB, and Cloud Spanner databases.
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=textabcd123-insecure-do-not-use-this
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:
Install Teleport on your Linux server:
-
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
-
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.comTELEPORT_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.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install-v16.2.1.sh | bash -s ${TELEPORT_VERSION} editionThe 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:
Change example.teleport.sh:443
to the host and port of your Teleport Proxy
Service. Set ELASTICACHE_URI
to the domain name and port of your ElastiCache
database:
ELASTICACHE_URI=""sudo teleport db configure create \ -o file \ --name="elasticache" \ --proxy=example.teleport.sh:443 \ --protocol="redis" \ --uri=${ELASTICACHE_URI?} \ --token=/tmp/token
Change example.teleport.sh:443
to the host and port of your Teleport Proxy
Service. Set MEMORYDB_URI
to the domain name and port of your ElastiCache
database:
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 role for Teleport
The Teleport Database Service needs AWS IAM permissions to provide access to ElastiCache or MemoryDB databases.
Create an IAM role for Teleport
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
- If you are running the Database Service in Kubernetes, you can use IAM Roles for Service Accounts (IRSA)
- 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.
The EC2 instance should be configured to use an EC2 instance profile. For more information, see: Using Instance Profiles.
Refer to IAM Roles for Service Accounts (IRSA) 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.
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 Database 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 Database 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.
Grant permissions
Attach the following AWS IAM permissions to the Database Service IAM role:
ElastiCache supports IAM authentication for Redis engine version 7.0 or above. This is the recommended way to configure Teleport access to ElastiCache.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ElastiCacheDescribeUsers",
"Effect": "Allow",
"Action": "elasticache:DescribeUsers",
"Resource": "*"
},
{
"Sid": "ElastiCacheConnect",
"Effect": "Allow",
"Action": "elasticache:Connect",
"Resource": [
"arn:aws:elasticache:us-east-2:aws-account-id:replicationgroup:replication-group",
"arn:aws:elasticache:us-east-2:aws-account-id:user:*"
]
}
]
}
Statement | Purpose |
---|---|
ElastiCacheDescribeUsers | Determine whether a user is compatible with IAM authentication. |
ElastiCacheConnect | Connect using IAM authentication. |
See Authenticating with IAM for ElastiCache for more information.
MemoryDB supports IAM authentication for Redis engine version 7.0 or above. This is the recommended way to configure Teleport access to MemoryDB.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "MemoryDBDescribeUsers",
"Effect": "Allow",
"Action": "memorydb:DescribeUsers",
"Resource": "*"
},
{
"Sid": "MemoryDBConnect",
"Effect": "Allow",
"Action": "memorydb:Connect",
"Resource": [
"arn:aws:memorydb:us-east-2:aws-account-id:replicationgroup:replication-group",
"arn:aws:memorydb:us-east-2:aws-account-id:user:*"
]
}
]
}
Statement | Purpose |
---|---|
MemoryDBDescribeUsers | Determine whether a user is compatible with IAM authentication. |
MemoryDBConnect | Connect using IAM authentication. |
See Authenticating with IAM for MemoryDB for more information.
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.
On the host where you will run the Database Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Database 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
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:
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"
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-01aws 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"
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=alicetsh db lsName Description Labels
--------------------------- --------------------------------------------------------- --------
my-cluster-mode-elasticache ...
my-elasticache ...
my-elasticache-reader ...
my-memorydb ...
tsh login --proxy=mytenant.teleport.sh --user=alicetsh db lsName 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:
The Database Service automatically authenticates Teleport-managed and
IAM-enabled users with the Redis server. No AUTH
command is required
after successful connection.
If you are connecting as a user that is not managed by Teleport and is not
IAM-enabled, the connection normally starts as the default
user.
Now you can authenticate the database user with its password:
AUTH my-database-user <USER_PASSWORD>
Now you can authenticate with the shared AUTH token:
AUTH <SHARED_AUTH_TOKEN>
For Redis deployments without the ACL system or legacy requirepass
directive enabled, no AUTH
command is required.
To log out of the database and remove credentials:
Remove credentials for a particular database instance.
tsh db logout my-elasticacheRemove 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 or DocumentDB 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 5432Connection 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:
- A Teleport user specifies an IAM role as the database user they wish to use when accessing AWS services that require IAM roles as database users. Databases that support using an IAM role as a database user include: DynamoDB, Keyspaces, Opensearch, Redshift, and Redshift Serverless.
- The
assume_role_arn
field is specified for the database resources or dynamic resource matchers.
When both of the above conditions are true for a database connection, the
Database Service performs a role chaining by assuming the IAM role specified
in assume_role_arn
first, then using that IAM role to assume the IAM role for
the database user.
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/teleport-db-service-role/i-* is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::111111111111:role/db-user-role
To allow IAM Role teleport-db-service-role
to assume IAM Role db-user-role
, the following is
generally required:
1. Configure Trust Relationships on db-user-role
teleport-db-service-role
or its AWS account should be set as Principal
in db-user-role
's trust
policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::aws-account-id:role/teleport-db-service-role"
},
"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/teleport-db-service-role"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "example-external-id"
}
}
}
]
}
2. Configure Permissions Policies on teleport-db-service-role
teleport-db-service-role
requires sts:AssumeRole
permissions, for example:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Resource": "arn:aws:iam::aws-account-id:role/db-user-role"
}
]
}
Note that this policy can be omitted when teleport-db-service-role
and db-user-role
are in the same
AWS account and teleport-db-service-role
's full ARN is configured as Principal in db-user-role
's
trust policy.
3. Configure Permissions Boundary on teleport-db-service-role
If teleport-db-service-role
does not have an attached
Permissions boundary
then you can skip this step.
Otherwise, the boundary policy attached to teleport-db-service-role
must include
sts:AssumeRole
permissions, for example:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Resource": "*"
}
]
}
You can test the trust relationship by running this AWS CLI command as teleport-db-service-role
:
aws sts assume-role --role-arn arn:aws:iam::111111111111:role/db-user-role --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.