Navigation

Generate X.509 Client Certificates

On this page

The MongoDB Enterprise Kubernetes Operator can deploy MongoDB instances with X.509 authentication enabled. If X.509 authentication has been enabled for the deployment, you must generate and use an X.509 certificate to connect to the deployment. This new client certificate must be signed by the same CA that signs the server certificates for the MongoDB deployment to accept it.

Use the procedure outlined in this document to use an X.509 certificate to connect to your X.509-enabled MongoDB deployment.

Prerequisites

Note

A full description of Transport Layer Security (TLS), Public Key Infrastructure (PKI) certificates, and Certificate Authorities is beyond the scope of this document. This page assumes prior knowledge of TLS and X.509 authentication.

Procedure

First create the client certificate. Then create a MongoDB user and connect to the X.509-enabled deployment.

1

Generate an X.509 client certificate.

For production use, your MongoDB deployment should use valid certificates generated and signed by a CA. You or your organization can generate and maintain an independent CA using Kubernetes-native tools such as cert-manager.

Obtaining and managing certificates is beyond the scope of this documentation.

Important

You must concatenate your client’s TLS certificate and the certificate’s key in a .pem file. You must present this .pem file when you connect to your X.509-enabled MongoDB deployment.

To learn about the properties that your client certificates must have, see Client Certificate Requirements in the MongoDB Manual.

2

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

kubectl config set-context $(kubectl config current-context) --namespace=<namespace>
3

Copy and save the following example ConfigMap.

Save the following ConfigMap as x509-mongodb-user.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
---
apiVersion: mongodb.com/v1
kind: MongoDBUser
metadata:
  name: new-x509-user
spec:
  username: "CN=my-x509-authenticated-user,OU=organizationalunit,O=organization"
  db: "$external"
  mongodbResourceRef:
    name: '<name of the MongoDB resource>'
  roles:
    - db: "admin"
      name: "readWriteAnyDatabase"

This ConfigMap .yaml file describes a MongoDBUser custom object. You can use these custom objects to create MongoDB users.

In this example, the ConfigMap describes the user as an X.509 user that the client can use to connect to MongoDB with the corresponding X.509 certificate.

4

Create the X.509 MongoDB user.

Run the following command to apply the ConfigMap and create the X.509 MongoDB user:

kubectl apply -f x509-mongodb-user.yaml

You should see an output similar to the following:

mongodbuser.mongodb.com/new-x509-user created
5

Verify your newly created user

Run the following command to check the state of the new-x509-user:

kubectl get mdbu/new-x509-user -o yaml

You should see an output similar to the following:

NAME            CREATED AT
new-x509-user   8m
6

Find the mount location of the CA.

Run the following command to find where in each pod the Kubernetes Operator mounted the CA secret:

kubectl get statefulset <metadata.name> -o yaml

In the output, find the secret-ca mount:

volumeMounts:
  - mountPath: /opt/scripts
    name: database-scripts
    readOnly: true
  - mountPath: /var/lib/mongodb-automation/secrets/ca
    name: secret-ca
    readOnly: true
  - mountPath: /var/lib/mongodb-automation/secrets/certs
    name: secret-certs
    readOnly: true

In the following step when you connect to your database deployment, append secret-ca to the mountPath, which forms the full path:

/var/lib/mongodb-automation/secrets/ca/secret-ca
7

Use your X.509 user to connect to the MongoDB deployment

Once you have created your X.509 user, try to connect to the deployment using the MongoDB Shell (mongosh):

mongosh --host {host} --port {port} --tls \
  --tlsCAFile </path/to/secret-ca> \
  --tlsCertificateKeyFile <your-cert>.pem \
  --authenticationMechanism MONGODB-X509  \
  --authenticationDatabase '$external'
mongosh --host {host} --port {port} --ssl \
  --sslCAFile </path/to/secret-ca> \
  --sslPEMKeyFile <your-cert>.pem \
  --authenticationMechanism MONGODB-X509 \
  --authenticationDatabase '$external'