Navigation
This documentation refers to the on-premises edition of MongoDB Charts. Read the Atlas service documentation to learn how to use MongoDB Charts with your Atlas project.

Connect to a TLS/SSL-Enabled Data Source

This document explains how to connect to a TLS/SSL-enabled MongoDB deployment as a data source. This document also demonstrates connecting to a deployment using x.509 client authentication.

Note

A full description of TLS/SSL, PKI certificates, and Certificate Authority is beyond the scope of this document. This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.

Connect over TLS/SSL without Client Certificate Validation

You can configure the MongoDB Charts client to connect to data sources with TLS/SSL enabled. If the deployment is running with TLS/SSL enabled, configuring your data source depends on whether the deployment’s certificate is:

  • Signed by a trusted root certificate authority, or
  • Self-signed or issued by an internal certificate authority.

Note

MongoDB deployments should use TLS/SSL 1.1 or later.

Select the appropriate tab based on how the deployment’s certificate is signed:

To connect Charts to a MongoDB deployment using a certificate signed by a trusted root certificate authority, you must append the ssl=true option to the data source Connection String URI.

For example, to connect to a deployment using TLS/SSL with SCRAM authentication, specify the following connection string when you add a data source:

mongodb://<user>:<password>@<server>:<port>/<database>?ssl=true

See Add a Data Source for instructions.

To connect Charts to a MongoDB deployment using a self-signed certificate or a certificate issued by an internal certificate authority, you must copy the certificate to the Docker volume.

The following steps copy the certificate to the Docker volume, redeploy the Charts application, and add a new data source configured to use TLS/SSL:

1

Copy the certificates to the Charts Docker volume.

The certificate must be in the .pem format and will be either:

  • the self-signed certificate used by the MongoDB deployment, or
  • the CA’s root certificate, if the certificate used by the MongoDB deployment was issued by a CA.

Choose the appropriate tab based on your operating system:

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Redeploy the Charts Docker stack.

docker stack rm mongodb-charts

Before redeploying, you need to ensure that the Charts containers are fully shut down. You can confirm this by running the docker ps command several times, until it shows no running Charts containers.

Once all Charts containers have shut down, relaunch the stack using the following command:

docker stack deploy -c charts-docker-swarm-19.09.yml mongodb-charts

Note

If you are using a different version of Charts, replace 19.09 with the version number of your release.

3

Add new TLS/SSL-enabled data source.

To connect Charts to a MongoDB deployment using a certificate signed by a trusted root certificate authority, you must append the ssl=true option to the data source Connection String URI.

For example, to connect to a deployment using TLS/SSL with SCRAM authentication, specify the following connection string when you add a data source:

mongodb://<user>:<password>@<server>:<port>/<database>?ssl=true

See Add a Data Source for instructions.

Connect over TLS/SSL with Client Certificate Validation/x.509

Use this procedure if the MongoDB deployment you wish to use for your data source requires Client Certificate Validation.

The process to configure your data source depends on whether the deployment’s certificate is:

  • Signed by a trusted root certificate authority, or
  • Self-signed or issued by an internal certificate authority.

Note

MongoDB deployments should use TLS/SSL 1.1 or later.

Select the appropriate tab based on how the deployment’s certificate is signed:

If your MongoDB deployment uses a certificate signed by a trusted root certificate authority, you must copy the client certificate to the Docker volume.

1

Copy the client certificate to the Charts Docker volume.

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Add a new TLS/SSL-enabled data source.

To connect Charts to a TLS/SSL-enabled MongoDB deployment, you must specify the following connection URI options for your data source:

Option Value
ssl true
sslclientcertificatekeyfile Path to your client certificate.

The following example command uses SCRAM authentication. Replace the certificate file values in the following command with the locations of your certificate files.

mongodb://<user>:<password@><server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem

Alternatively, to use x.509 Client Authentication you must:

  • Remove the <user> and <password>,
  • Specify the authMechanism=MONGODB-X509 option.
mongodb://<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&authMechanism=MONGODB-X509

For instructions on configuring your data source, see Add a Data Source.

If your MongoDB deployment uses a self-signed certificate or a certificate issued by an internal certificate authority, you must copy the certificate to the Docker volume.

1

Copy the client and CA certificates to the Charts Docker volume.

You must upload two certificate files to the Charts Docker volume:

  • The client certificate, including the private key.
  • The certificate for the deployment’s CA. You do not need to include the private key with this certificate.

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Add a new TLS/SSL-enabled data source.

To connect Charts to a TLS/SSL-enabled MongoDB deployment, you must specify the following connection URI options for your data source:

Option Value
ssl true
sslclientcertificatekeyfile Path to your client certificate.
sslcertificateauthorityfile Path to your certificate authority certificate.

The following example command uses SCRAM authentication. Replace the certificate file values in the following command with the locations of your certificate files.

mongodb://<user>:<password>@<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&sslcertificateauthorityfile=/mongodb-charts/volumes/db-certs/ca.pem

Alternatively, to use x.509 Client Authentication you must:

  • Remove the <user> and <password>,
  • Specify the authMechanism=MONGODB-X509 option.
mongodb://<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&sslcertificateauthorityfile=/mongodb-charts/volumes/db-certs/ca.pem&authMechanism=MONGODB-X509

For instructions on configuring your data source, see Add a Data Source.