Teleport
Database Access with Amazon DocumentDB
- Edge version
- Version 17.x
- Version 16.x
- Version 15.x
- Older Versions
Teleport can provide secure access to Amazon DocumentDB via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.
In this guide, you will:
- Configure your Amazon DocumentDB database with IAM authentication.
- Add the database to your Teleport cluster.
- Connect to the database via Teleport.
How it works
The Teleport Database Service uses IAM authentication to communicate with Amazon DocumentDB. When a user connects to the database via Teleport, the Teleport Database Service obtains AWS credentials and authenticates to AWS as an IAM principal with permissions to access the database.
This guide shows how to register a single Amazon DocumentDB 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 16.4.10 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 a DocumentDB cluster.
IAM authentication and TLSTeleport uses IAM authentication to connect users to DocumentDB, which is only supported for DocumentDB 5.0 or higher.
In addition, the DocumentDB cluster must have Transport Layer Security (TLS) enabled. TLS is enabled by default when using the default parameter group.
-
Command-line client
mongosh
ormongo
installed and added to your system'sPATH
environment variable. -
A host, e.g., an EC2 instance, where you will run the Teleport Database Service.
-
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:
tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.10
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 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.4.10.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.
On the node that is running the Database Service, create a configuration file. Use your DocumentDB cluster endpoint and port as the URI:
sudo teleport db configure create \ -o file \ --name="my-docdb" \ --proxy=example.teleport.sh:443 \ --protocol=mongodb \ --token=/tmp/token \ --uri="my-docdb.cluster-abcdefghijklm.us-east-1.docdb.amazonaws.com:27017"
The command will generate a Database Service configuration to proxy your AWS
DocumentDB cluster and save the configuration to /etc/teleport.yaml
.
Step 3/6. Create an IAM role for the Database Service
First, visit the IAM > Policies page of the AWS Console, then press "Create policy".
Use the JSON option for Policy editor and paste in the following policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds:DescribeDBClusters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Resource": "*",
"Condition": {
"StringEquals": {"iam:ResourceTag/TeleportDatabaseService": "Allowed"}
}
}
]
}
This policy allows Teleport Database Service to retrieve DocumentDB cluster
metadata and assume IAM roles to authenticate as DocumentDB users. Note that
the sts:AssumeRole
has a resource tag condition to limit the IAM roles the
Teleport Database Service can assume.
Click Next and give the policy a name. In this guide, we will use the example
name TeleportDatabaseAccessDocumentDB
.
Now 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" or the intended use case, then click Next.
On the "Add Permissions" page, find and select the
TeleportDatabaseAccessDocumentDB
policy that is created in the previous step.
Click "Next" and give the role a name. 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.
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
.
The Database Service will proxy the Amazon DocumentDB cluster with the URI you specified earlier. Keep in mind that AWS IAM changes may not propagate immediately and can take a few minutes to come into effect.
Step 5/6. Create an IAM role for a DocumentDB user
In this step, we will create an IAM role that the Teleport Database Service can assume to authenticate to DocumentDB on behalf of a Teleport user.
Create an IAM role
Navigate back to the Roles page on the AWS Web Console 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:
Skip the "Add Permissions" page by clicking "Next", and give the role a name. In this guide, we will use the example "teleport-docdb-user" for this role.
Now click Add new tag at Step 3, use TeleportDatabaseService
for the key
and Allowed
for the value. Then click Create Role to complete the process.
Create a DocumentDB user
Log in to your DocumentDB cluster with your master username and password from a
machine that has network access to the DocumentDB cluster. Create a DocumentDB
user with the IAM role ARN as username and specify MONGODB-AWS
in the
mechanisms for authentication:
use $external;db.createUser( { user: "arn:aws:iam::123456789012:role/teleport-docdb-user", mechanisms: ["MONGODB-AWS"], roles: [ { role: "root", db: "admin" }, ] });
This example creates a DocumentDB IAM user with root privileges. You can adjust the privileges as required.
This step is a one-time setup that must use password authentication. However, after creating the first IAM user, you can skip password authentication by accessing DocumentDB through Teleport and creating more DocumentDB IAM users using the first IAM user.
Step 6/6 Connect
Once the Database Service has started and joined the cluster, log in to see the registered databases:
tsh login --proxy=example.teleport.sh:443 --user=alicetsh db lsName Description Labels
-------- ----------- --------
my-docdb env=dev
Retrieve credentials for the database and connect to it as the teleport-docdb-user
user:
tsh db connect --db-user=teleport-docdb-user --db-name=test my-docdb
Log out of the database and remove credentials:
tsh db logout rds-example
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.
Unable to authenticate using mechanism "MONGODB-AWS" error
You may encounter the following error when IAM authentication fails:
tsh db connect --db-user=teleport-docdb-user --db-name=test my-docdb...MongoServerSelectionError: error connecting to the database connection() error occurred during connection handshake: auth error: sasl conversation error: unable to authenticate using mechanism "MONGODB-AWS": Authentication failed.ERROR: exit status 1
Make sure the IAM role exists as a DocumentDB user in the "$external" database
of the target DocumentDB cluster and the DocumentDB user is configured with
MONGODB-AWS
mechanisms for authentication.
See Authentication using IAM identity for more details.
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.
- Learn more about Authentication using IAM identity for DocumentDB for more details.