Database Access with MongoDB Atlas

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

In this guide, you will:

1. Configure an MongoDB Atlas with mutual TLS authentication or AWS IAM.
2. Join the MongoDB Atlas database to your Teleport cluster.
3. Connect to the MongoDB Atlas database via the Teleport Database Service.

• Self-Hosted
• Teleport Enterprise Cloud

Prerequisites

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

  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.

• MongoDB Atlas cluster.
• A host, e.g., an Amazon 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 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 protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.2
  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/4. Set up the Teleport Database Service

The Database Service requires a valid auth token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service and save it in /tmp/token on the node that will run the Database Service:

tctl tokens add --type=db

Install Teleport on the host where you will run the Teleport Database Service:

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://goteleport.com/static/install.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.

Next, start the Database Service.

sudo teleport db start \  --token=/tmp/token \  --auth-server=teleport.example.com:443 \  --name=mongodb-atlas \  --protocol=mongodb \  --uri=mongodb+srv://cluster0.abcde.mongodb.net \  --ca-cert=/path/to/letsencrypt/isrgrootx1.pem \  --labels=env=dev

version: v3
teleport:
  auth_token: "/tmp/token"
  proxy_server: teleport.example.com:443

# disable services that are on by default
ssh_service: { enabled: no }
proxy_service: { enabled: no }
auth_service: { enabled: no }

db_service:
  enabled: "yes"
  databases:
  - name: "mongodb-atlas"
    protocol: "mongodb"
    uri: "mongodb+srv://cluster0.abcde.mongodb.net"
    tls:
      ca_cert_file: "/path/to/letsencrypt/isrgrootx1.pem"
    static_labels:
      env: "dev"

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

sudo teleport db start \  --token=/tmp/token \  --auth-server=mytenant.teleport.sh:443 \  --name=mongodb-atlas \  --protocol=mongodb \  --uri=mongodb+srv://cluster0.abcde.mongodb.net \  --ca-cert=/path/to/letsencrypt/isrgrootx1.pem \  --labels=env=dev

version: v3
teleport:
  auth_token: "/tmp/token"
  proxy_server: mytenant.teleport.sh:443
db_service:
  enabled: "yes"
  databases:
  - name: "mongodb-atlas"
    protocol: "mongodb"
    uri: "mongodb+srv://cluster0.abcde.mongodb.net"
    tls:
      ca_cert_file: "/path/to/letsencrypt/isrgrootx1.pem"
    static_labels:
      env: "dev"

See below for details on how to configure the Teleport Database Service.

Connection endpoint

You will need to provide your Atlas cluster's connection endpoint for the db_service.databases[*].uri configuration option or --uri CLI flag. You can find this via the Connect dialog on the Database Deployments overview page:

Go through the "Setup connection security" step and select "Connect with the MongoDB shell" to view the connection string:

Use only the scheme and hostname parts of the connection string in the URI:

--uri=mongodb+srv://cluster0.abcde.mongodb.net

Atlas CA certificate

MongoDB Atlas uses certificates signed by Let's Encrypt.

Download the Let's Encrypt root certificate and use it as a CA in the Database Service configuration:

curl -o /tmp/isrgrootx1.pem https://letsencrypt.org/certs/isrgrootx1.pem.txt

You can then use /tmp/isrgrootx1.pem as the value of the db_service.databases[*].ca_cert_file configuration option or --ca-cert CLI flag.

Step 2/4. 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.

If you opt for a stricter selection of database names for your user, which differs from the wildcard approach illustrated in this guide, it is essential to include the admin database. This ensures MongoDB clients won't have issues while connecting and executing operations such as retrieving server information, listing databases, and aborting transactions.

Step 3/4. Configure Atlas

Teleport MongoDB Atlas integration supports two methods of authentication:

• Self-managed X.509: This method relies on certificates for authentication, with MongoDB Atlas trusting the Teleport certificates.
• AWS IAM: The authentication is done using AWS credentials fetched by Teleport.

• Self-managed X.509
• AWS IAM

First, obtain Teleport CA certificate by running the following tctl auth sign command against your Teleport cluster:

tctl auth sign --format=mongodb --host=mongo --out=mongo

The --host and --ttl flag value doesn't matter in this case since you'll only use the CA certificate which this command will output to mongo.cas file. You can discard the other mongo.crt file.

Go to the Security / Advanced configuration section of your Atlas cluster and toggle "Self-managed X.509 Authentication" on:

Paste the contents of mongo.cas file in the Certificate Authority edit box and click Save.

Create a MongoDB user

On the Security / Database Access page add a new database user with Certificate authentication method:

Make sure to specify the user as CN=<user> as shown above since MongoDB treats the entire certificate subject as a username. When connecting to a MongoDB cluster, say, as a user alice, Teleport will sign an ephemeral certificate with CN=alice subject.

Note

Case matters so make sure to specify Common Name in the username with capital letters CN=.

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:

• Instance Metadata Service
• 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.

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>

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

Create a MongoDB IAM role

Navigate to the AWS IAM console. In the navigation pane, choose Roles and then choose Create role. Next, select the "Custom trust policy" type. Edit the trust policy to allow the Teleport Database service IAM role to assume this role so that the Teleport can fetch the necessary credentials to authenticate to MongoDB:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111111111111:role/teleport-database-access",
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Your role won’t require any permission, so you can leave it empty on the Add Permissions step. Then, choose a name for it and create it. In this guide, we will the name teleport-access.

Create a MongoDB User

On the Security / Database Access page add a new database user with AWS IAM authentication method, and choose "IAM Role" as the IAM User type. Then, fill in the AWS ARN field with the ARN of the newly created IAM role. In the Database User Privileges section, give the user sufficient privileges to access the desired database data.

Please note that Teleport does not support authentication using AWS IAM users; it exclusively supports authentication using AWS IAM roles.

Step 4/4. Connect

Log into your Teleport cluster and see available databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name          Description Labels
------------- ----------- --------
mongodb-atlas             env=dev

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
Name          Description Labels
------------- ----------- --------
mongodb-atlas             env=dev

tsh db connect --db-user=alice --db-name dev mongodb-atlas

tsh db connect --db-user=role/teleport-access --db-name dev mongodb-atlas

tsh db connect --db-user=arn:aws:iam::111111111111:role/teleport-access --db-name dev mongodb-atlas

Either the mongosh or mongo command-line clients should be available in PATH in order to be able to connect. The Database Service attempts to run mongosh first and, if mongosh is not in PATH, runs mongo.

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout mongodb-atlas
Remove credentials for all database instances.
tsh db logout

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.

Further reading

• Which certificate authority signs MongoDB Atlas cluster TLS certificates?
• Self-managed X.509 authentication
• AWS IAM authentication