Database Access with Self-Hosted MongoDB

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

The Teleport Database Service proxies traffic from database clients to self-hosted databases in your infrastructure. Teleport maintains a certificate authority for database clients. You configure your database to trust the Teleport database client CA, and the Teleport Database Service presents certificates signed by this CA when proxying user traffic. With this setup, there is no need to store long-lived credentials for self-hosted databases.

Meanwhile, the Teleport Database Service verifies self-hosted databases by checking their TLS certificates against either the Teleport database CA or a custom CA chosen by the user.

In this guide, you will:

1. Configure your MongoDB database for Teleport access.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

How it works

The Teleport Database Service authenticates to your self-hosted MongoDB database using mutual TLS. MongoDB trusts the Teleport certificate authority for database clients, and presents a certificate signed by either the Teleport database CA or a custom CA. When a user initiates a database session, the Teleport Database Service presents a certificate signed by Teleport. The authenticated connection then proxies client traffic from the user.

• Self-Hosted
• Teleport Enterprise Cloud

Prerequisites

• A running Teleport cluster version 16.4.7 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 cluster (standalone or replica set) version 3.6 or newer.

  Note

  Teleport database access supports MongoDB 3.6 and newer. Older versions have not been tested and are not guaranteed to work. MongoDB 3.6 was released in November 2017 and reached EOL in April 2021 so if you're still using an older version, consider upgrading.

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

  For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  16.4.7
  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.

• A certificate authority for MongoDB Replica Set, and the public certificate for that CA, in PEM format: /path/to/your/ca.crt. You can also configure Teleport to trust this CA for standalone MongoDB instances.

  Why do I need my own CA?

  Distributed databases like MongoDB Replica Set use mTLS for node-to-node communication. Teleport requires that you have your own CA to issue certificates for node-to-node mTLS communication.

  Teleport uses a split-CA architecture for database access. The Teleport db CA issues server certificates and the db_client CA issues client certificates.

  Databases are configured to trust the Teleport db_client CA for client authentication, but not the db CA. Additionally, Teleport only issues ephemeral db_client CA certificates.

  When a MongoDB Replica Set node connects to another MongoDB Replica Set node, it must present a certificate that the other node trusts for client authentication. Since Teleport does not issue long-lived db_client certificates, the node needs to have a long-lived certificate issued by another CA that its peer node trusts.

  The split db and db_client CA architecture was introduced as a security fix in Teleport versions: 13.4.17, 14.3.7, and 15.

  See Database CA Migrations for more information.

Step 1/3. Install and configure Teleport

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 and configure Teleport where you will run the Teleport Database Service:

sudo teleport db configure create \   -o file \   --token=/tmp/token \   --proxy=teleport.example.com:443 \   --name=example-mongo \   --protocol=mongodb \   --uri=mongodb://mongo.example.com:27017 \   --labels=env=dev 

sudo teleport db configure create \   -o file \   --token=/tmp/token \   --proxy=mytenant.teleport.sh:443 \   --name=example-mongo \   --protocol=mongodb \   --uri=mongodb://mongo.example.com:27017 \   --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

helm repo add teleport https://charts.releases.teleport.dev

helm repo update

JOIN_TOKEN=$(cat /tmp/token)
helm install teleport-kube-agent teleport/teleport-kube-agent \  --create-namespace \  --namespace teleport-agent \  --set roles=db \  --set proxyAddr=teleport.example.com:443 \  --set authToken=${JOIN_TOKEN?} \  --set "databases[0].name=example-mongo" \  --set "databases[0].uri=mongodb://mongo.example.com:27017" \  --set "databases[0].protocol=mongodb" \  --set "databases[0].static_labels.env=dev" \  --version 16.4.7

JOIN_TOKEN=$(cat /tmp/token)
helm install teleport-kube-agent teleport/teleport-kube-agent \  --create-namespace \  --namespace teleport-agent \  --set roles=db \  --set proxyAddr=mytenant.teleport.sh:443 \  --set authToken=${JOIN_TOKEN?} \  --set "databases[0].name=example-mongo" \  --set "databases[0].uri=mongodb://mongo.example.com:27017" \  --set "databases[0].protocol=mongodb" \  --set "databases[0].static_labels.env=dev" \  --version 16.4.3

kubectl -n teleport-agent get pods
NAME                    READY   STATUS    RESTARTS   AGEteleport-kube-agent-0   1/1     Running   0          32s

You can specify either a single connection address or a MongoDB connection string as a URI. For example, when connecting to a replica set:

--uri="mongodb://mongo1.example.com:27017,mongo2.example.com:27017/?replicaSet=rs0"

By default, Teleport will connect to the primary replica set member. If you'd like to connect to a secondary instead, Teleport will respect readPreference connection string setting:

--uri="mongodb://mongo1.example.com:27017,mongo2.example.com:27017/?replicaSet=rs0&readPreference=secondary"

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 2/3. Configure MongoDB

Create a MongoDB user

Teleport will use X.509 authentication when connecting to a MongoDB instance. Users authenticating with client certificates must be created in the $external MongoDB authentication database.

MongoDB treats the entire Subject line of the client certificate as a username. When connecting to a MongoDB server, say as a user alice, Teleport will sign an ephemeral certificate with the CN=alice subject.

To create this user in the database, connect to it using the mongosh or mongo shell and run the following command:

db.getSiblingDB("$external").runCommand(
  {
    createUser: "CN=alice",
    roles: [
      { role: "readWriteAnyDatabase", db: "admin" }
    ]
  }
)

Update the roles accordingly to grant the user appropriate database permissions.

Set up mutual TLS

allow:
  impersonate:
    users: ["Db"]
    roles: ["Db"]

tctl auth sign --format=mongodb --host=mongo.example.com --out=mongo --ttl=2190h

tctl auth export --type=db-client > db-client-ca.crt
cat /path/to/your/ca.crt db-client-ca.crt > /etc/certs/mongo.cas

  databases:
  - name: "example-mongodb"
    protocol: "mongodb"
    uri: "mongodb.example.com:27017"
    static_labels:
      "env": "example"
    tls:
      ca_cert_file: "/path/to/your/ca.crt"

Use the generated secrets to enable mutual TLS in your mongod.conf configuration file and restart the database:

net:
  ssl:
    mode: requireSSL
    PEMKeyFile: /etc/certs/mongo.crt
    CAFile: /etc/certs/mongo.cas

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/certs/mongo.crt
    CAFile: /etc/certs/mongo.cas

When configuring a replica set, make sure to do it for each member and use secrets generated for the particular server.

Once mutual TLS has been enabled, you will no longer be able to connect to the cluster without providing a valid client certificate. You can use the net.tls.allowConnectionsWithoutCertificates setting to allow connections from clients that do not present a certificate.

See Configure TLS/SSL in the MongoDB documentation for more details.

Step 3/3. Connect

Log in to your Teleport cluster and see available databases:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name          Description     Labels
------------- --------------- --------
example-mongo Example MongoDB env=dev

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
Name          Description     Labels
------------- --------------- --------
example-mongo Example MongoDB env=dev

To retrieve credentials for a database and connect to it:

tsh db connect --db-user=alice --db-name dev example-mongo

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout example-mongo
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.