Navigation

Secure Client Authentication with X.509

The MongoDB Enterprise Kubernetes Operator can use X.509 certificates to authenticate your client applications to your MongoDB deployments.

This guide instructs you on how to configure:

  • X.509 authentication from clients to your MongoDB instances.
  • TLS to encrypt connections between MongoDB hosts in a replica set or sharded cluster.
  • TLS to encrypt connections client applications and MongoDB deployments.

Prerequisites

Before you secure your MongoDB deployment using X.509 client authentication, complete the following:

Note

You can’t secure a Standalone Instance.

Configure X.509 Client Authentication for a Replica Set

1

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>
2

Copy the highlighted section of this replica set resource.

Change the highlighted settings of this YAML file to match your desired replica set configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-replica-set>
spec:
  members: 3
  version: 4.2.1
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true
18
19
20
21
22
23
24
  security:
    tls:
      enabled: true
    authentication:
      enabled: true
      modes: ["X509"]
...
3

Paste the copied example section into your existing replica set resource.

Open your preferred text editor and paste the object specification at the end of your resource file in the spec section.

4

Configure the TLS settings for your replica set resource.

To enable TLS in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
boolean Optional

If this value is true, TLS is enabled on the MongoDB deployment.

By default, Kubernetes Operator requires hosts to use and accept TLS encrypted connections.

true
5

Configure the general X.509 settings for your replica set resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
boolean Optional If this value is true, authentication is enabled on the MongoDB deployment. true
spec.security
.authentication
array Conditional If you enabled authentication, you must set an authentication mechanism. Accepted values are X509. X509
6

Save your replica set config file.

7

Update and restart your replica set deployment.

Invoke the following Kubernetes command to update and restart your replica set:

kubectl apply -f <replica-set-conf>.yaml
8

Check the status of your deployment.

The Kubernetes Operator creates the MongoDB resources and requests the Kubernetes Certificate Authority to approve the database host’s certificates. Run the following command to verify that the certificates are pending approval:

kubectl get mdb <resource-name> -o yaml -w

The status field of the output should resemble the following:

status:
  lastTransition: 2019-05-01T15:36:59Z
  message: Not all certificates have been approved by Kubernetes CA
  phase: Failed
  type: ""
  version: ""

If you do not see the status.message above, see Troubleshooting the Kubernetes Operator to help diagnose the issue.

9

Retrieve the CSRs for each host and agent in your deployment.

Invoke the following command to retrieve the CSRs for each host:

kubectl get csr

The command’s output resembles the following:

1
2
3
4
5
6
7
NAME                                        AGE       REQUESTOR                                                   CONDITION
mms-automation-agent.mongodb                15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
mms-backup-agent.mongodb                    15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
mms-monitoring-agent.mongodb                15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
my-secure-rs-0.mongodb                      33s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-rs-1.mongodb                      31s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-rs-2.mongodb                      24s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
10

Approve the CSR for each host in your deployment.

Using the values returned in the NAME column, approve each certificate from the previous command’s output using the following command:

kubectl certificate approve <NAME>

Example

The following commands approve the CSRs for the replica set example:

1
2
3
kubectl certificate approve my-secure-rs-0.mongodb
kubectl certificate approve my-secure-rs-1.mongodb
kubectl certificate approve my-secure-rs-2.mongodb

kubectl prints a message to the console when a certificate is approved.

11

Approve the CSR for each agent in your deployment.

Using the values returned in the NAME column, approve each certificate from the previous command’s output using the following command:

kubectl certificate approve <NAME>

Example

The following commands approve the CSRs for the replica set example:

1
2
3
kubectl certificate approve mms-automation-agent.mongodb
kubectl certificate approve mms-backup-agent.mongodb
kubectl certificate approve mms-monitoring-agent.mongodb

kubectl prints a message to the console when a certificate is approved.

12

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when something changes until the status phase achieves the Running state.

See Troubleshooting the Kubernetes Operator for information about the resource deployment statuses.

Configure X.509 Client Authentication for a Sharded Cluster

1

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>
2

Copy the highlighted section of this sharded cluster resource.

Change the highlighted settings of this YAML file to match your desired sharded cluster configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-sharded-cluster>
spec:
  shardCount: 2
  mongodsPerShardCount: 3
  mongosCount: 2
  configServerCount: 3
  version: 4.2.1
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ShardedCluster
  persistent: true
21
22
23
24
25
26
27
  security:
    tls:
      enabled: true
    authentication:
      enabled: true
      modes: ["X509"]
...
3

Paste the copied example section into your existing sharded cluster resource.

Open your preferred text editor and paste the object specification at the end of your resource file in the spec section.

4

Configure the TLS settings for your sharded cluster resource.

To enable TLS in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
boolean Optional

If this value is true, TLS is enabled on the MongoDB deployment.

By default, Kubernetes Operator requires hosts to use and accept TLS encrypted connections.

true
5

Configure the general X.509 settings for your sharded cluster resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
boolean Optional If this value is true, authentication is enabled on the MongoDB deployment. true
spec.security
.authentication
array Conditional If you enabled authentication, you must set an authentication mechanism. Accepted values are X509. X509
6

Save your sharded cluster config file.

7

Update and restart your sharded cluster deployment.

Invoke the following Kubernetes command to update and restart your sharded cluster:

kubectl apply -f <sharded-cluster-conf>.yaml
8

Check the status of your deployment.

The Kubernetes Operator creates the MongoDB resources and requests the Kubernetes Certificate Authority to approve the database host’s certificates. Run the following command to verify that the certificates are pending approval:

kubectl get mdb <resource-name> -o yaml -w

The status field of the output should resemble the following:

status:
  lastTransition: 2019-05-01T15:36:59Z
  message: Not all certificates have been approved by Kubernetes CA
  phase: Failed
  type: ""
  version: ""

If you do not see the status.message above, see Troubleshooting the Kubernetes Operator to help diagnose the issue.

9

Retrieve the CSRs for each host and agent in your deployment.

Invoke the following command to retrieve the CSRs for each host:

kubectl get csr

The command’s output resembles the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
NAME                                        AGE       REQUESTOR                                                   CONDITION
my-secure-sc-0-0.mongodb                    30s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-0-1.mongodb                    28s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-0-2.mongodb                    27s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-1-0.mongodb                    22s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-1-1.mongodb                    13s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-1-2.mongodb                    6s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-config-0.mongodb               36s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-config-1.mongodb               34s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-config-2.mongodb               32s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-mongos-0.mongodb               49s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
my-secure-sc-mongos-1.mongodb               42s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
10

Approve the CSR for each host in your deployment.

Using the values returned in the NAME column, approve each certificate from the previous command’s output using the following command:

kubectl certificate approve <NAME>

Example

The following commands approve the CSRs for the sharded cluster example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
kubectl certificate approve my-secure-sc-0-0.mongodb
kubectl certificate approve my-secure-sc-0-1.mongodb
kubectl certificate approve my-secure-sc-0-2.mongodb
kubectl certificate approve my-secure-sc-1-0.mongodb
kubectl certificate approve my-secure-sc-1-1.mongodb
kubectl certificate approve my-secure-sc-1-2.mongodb
kubectl certificate approve my-secure-sc-config-0.mongodb
kubectl certificate approve my-secure-sc-config-1.mongodb
kubectl certificate approve my-secure-sc-config-2.mongodb
kubectl certificate approve my-secure-sc-mongos-0.mongodb
kubectl certificate approve my-secure-sc-mongos-1.mongodb

kubectl prints a message to the console when a certificate is approved.

11

Approve the CSR for each agent in your deployment.

Using the values returned in the NAME column, approve each certificate from the previous command’s output using the following command:

kubectl certificate approve <NAME>

Example

The following commands approve the CSRs for the sharded cluster example:

1
2
3
kubectl certificate approve mms-automation-agent.mongodb
kubectl certificate approve mms-backup-agent.mongodb
kubectl certificate approve mms-monitoring-agent.mongodb

kubectl prints a message to the console when a certificate is approved.

12

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when something changes until the status phase achieves the Running state.

See Troubleshooting the Kubernetes Operator for information about the resource deployment statuses.