Skip to main content
This is a fake video link, YouTube API key is not available
This is a fake video link, YouTube API key is not available

Length: 03:44

Version: 14.x

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.

Prerequisites​

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

  • 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@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # 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 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 the host where you will run the Teleport Database Service:

Select an edition, then follow the instructions for that edition to install Teleport.

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

Next, start the Database Service.

On the node where you will run the Database Service, start Teleport, pointing the --auth-server flag at the address of your Teleport Proxy 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
note

The --auth-server flag must point to the Teleport cluster's Proxy Service endpoint because the Database Service always connects back to the cluster over a reverse tunnel.

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:

Connect

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​

tip

To modify an existing user to provide access to the Database Service, see Database Access Access Controls

Create a local Teleport user with the built-in access role:

$ tctl users add \
  --roles=access \
  --db-users="*" \
  --db-names="*" \
  alice
FlagDescription
--rolesList of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport.
--db-usersList of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.
--db-namesList of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database.
warning

Database names are only enforced for PostgreSQL and MongoDB databases.

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.

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

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

To retrieve credentials for a database and connect to it:

$ tsh db connect --db-user=alice --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​

  • See the YAML configuration reference for updating dynamic resource matchers or static database definitions.

Further reading​