Fork me on GitHub
Teleport

Database Access with MongoDB Atlas

MongoDB Atlas

In this guide you will:

  1. Configure Teleport for accessing your MongoDB Atlas cluster.
  2. Configure self-managed X.509 authentication on your Atlas cluster.
  3. Connect to your Atlas cluster via Teleport.

Prerequisites

Step 1/3. Configure Teleport

Setup Teleport Auth and Proxy services

Download the latest version of Teleport for your platform from our downloads page and follow the installation instructions.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt ACME protocol. We will assume that you have configured DNS records for teleport.example.com and *.teleport.example.com to point to the Teleport node.

Generate Teleport config with ACME enabled:

$ teleport configure --cluster-name=teleport.example.com --acme [email protected] -o file
Web Proxy Port
Teleport uses TLS-ALPN-01 ACME challenge to validate certificate requests which only works on port 443. As such, in order to use ACME for certificate management, web proxy needs to be accessible on port 443.

Start Teleport Auth and Proxy services:

$ sudo teleport start

Setup Teleport Database service

Database service requires a valid auth token to connect to the cluster. Generate one and save it in /tmp/token:

$ tctl tokens add --type=db

Start Teleport Database service:

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

See below for details on --uri and --ca-cert flags.

Note
The --auth-server flag must point to the Teleport cluster's proxy endpoint because database service always connects back to the cluster over a reverse tunnel.

Configuration file

If you're starting Database agent with YAML configuration instead of CLI flags, the following config is equivalent to the above command:

teleport:
  auth_token: "/tmp/token"
  auth_servers:
  - "teleport.example.com:443"
db_service:
  enabled: "yes"
  databases:
  - name: "mongodb-atlas"
    protocol: "mongodb"
    uri: "mongodb+srv://cluster0.abcde.mongodb.net"
    ca_cert_file: "/path/to/letsencrypt/isrgrootx1.pem"
    static_labels:
      env: "dev"

See full YAML reference for details.

Connection endpoint --uri

To find out your Atlas cluster's connection endpoint for the URI, use 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:

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 --ca-cert

MongoDB Atlas uses certificates signed by Let's Encrypt as described in Which certificate authority signs MongoDB Atlas cluster TLS certificates?

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

--ca-cert=/tmp/isrgrootx1.pem

Create Teleport user

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

$ tctl users add --roles=access alice

The access role allows users to see all connected database servers, but database names and accounts are restricted to the user's db_names and db_users traits. Normally, these traits come from the identity provider. For the local user you've just created you can update them manually to allow it to connect to any database as any database user.

First, export the user resource:

$ tctl get users/alice > alice.yaml

Update the resource to include the following traits:

traits:
  db_users:
  - "*"
  db_names:
  - "*"

Update the user:

$ tctl create alice.yaml -f

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

Step 2/3. Configure Atlas

Enable self-managed X.509 authentication

Teleport will authenticate with MongoDB Atlas using self-managed X.509 authentication.

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:

X.509

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

Create MongoDB user

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

Add user

Make sure to specify the user as CN=<user> like 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 3/3. 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 connect to a particular database instance, first retrieve its certificate using tsh db login command:

tsh db login mongodb-atlas
Tip
You can be logged into multiple databases simultaneously.

You can optionally specify the database name and the user to use by default when connecting to the database instance:

tsh db login --db-user=alice mongodb-atlas

Once logged in, connect to the database:

tsh db connect mongodb-atlas
Note
The mongo command-line client should be available in PATH in order to be able to connect.

If you would like to see the native mongo shell connect command, run:

tsh db config --format=cmd mongodb-atlas

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

Have a suggestion or can’t find something?
IMPROVE THE DOCS