Secure Client Authentication with X.509¶

On this page

General Prerequisites
Configure X.509 Client Authentication for a Replica Set
Configure X.509 Client Authentication for a Sharded Cluster

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.

Note

You can’t secure a Standalone Instance of MongoDB in a Kubernetes cluster.

General Prerequisites¶

Before you secure your MongoDB deployment using TLS encryption, complete the following:

Enabling X.509 authentication at the project level configures all agents to use X.509 client authentication when communicating with MongoDB deployments.

X.509 client authentication requires one of the following:

Cloud Manager
Ops Manager 4.1.7 or later
Ops Manager 4.0.11 or later

Configure X.509 Client Authentication for a Replica Set¶

Prerequisites¶

Before you secure your replica set using X.509, deploy a TLS-encrypted replica set.

Enable X.509 Client Authentication¶

5

Copy the sample replica set resource.¶

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

---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-replica-set>
spec:
  members: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
            # Must match metadata.name in ConfigMap file
      name: <configMap.metadata.name>
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true

copy

  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
    authentication:
      enabled: true
      modes: ["X509"]
...

6

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.

7

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` `.enabled`	boolean	Required	Set this value to `true` to enable authentication on the MongoDB deployment.	`true`
`spec.security` `.authentication` `.modes`	array	Conditional	Set this value to `["X509"]`.	`["X509"]`

8

Save your replica set config file.¶

9

Apply your changes to your replica set deployment.¶

Invoke the following Kubernetes command to update your replica set:

copy

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

10

Track the status of your deployment.¶

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

copy

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

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

Renew X.509 Certificates for a Replica Set¶

If you have already created certificates, we recommend that you renew them periodically using the following procedure.

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.

Note

If you are deploying an Ops Manager resource on a multi-Kubernetes-cluster deployment:

Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".
Set the --namespace to the same scope that you used for your multi-Kubernetes-cluster deployment, such as: kubectl config --namespace "mongodb".

copy

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

2

Renew the secret for your TLS certificates.¶

Run this kubectl command to renew an existing secret that stores the replica set’s certificates:

copy

kubectl create secret tls <prefix>-<metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

3

Renew the secret for your agents’ X.509 certificates.¶

Run this kubectl command to renew an existing secret that stores the agents’ X.509 certificates:

copy

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

Configure X.509 Client Authentication for a Sharded Cluster¶

Prerequisites¶

Before you secure your sharded cluster using X.509, deploy a TLS-encrypted sharded cluster.

Enable X.509 Client Authentication¶

1

Copy the sample sharded cluster resource.¶

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

---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-sharded-cluster>
spec:
  shardCount: 2
  mongodsPerShardCount: 3
  mongosCount: 2
  configServerCount: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ShardedCluster
  persistent: true

copy

  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
    authentication:
      enabled: true
      modes: ["X509"]
...

2

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.

3

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` `.enabled`	boolean	Required	Set this value to `true` to enable authentication on the MongoDB deployment.	`true`
`spec.security` `.authentication` `.modes`	array	Conditional	Set this value to `["X509"]`.	`["X509"]`

4

Save your sharded cluster config file.¶

5

Update and restart your sharded cluster deployment.¶

In any directory, invoke the following Kubernetes command to update and restart your sharded cluster:

copy

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

6

Track the status of your deployment.¶

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

copy

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

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

Renew X.509 Certificates for a Sharded Cluster¶

If you have already created certificates, we recommend that you renew them periodically using the following procedure.

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.

Note

If you are deploying an Ops Manager resource on a multi-Kubernetes-cluster deployment:

Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".
Set the --namespace to the same scope that you used for your multi-Kubernetes-cluster deployment, such as: kubectl config --namespace "mongodb".

copy

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

2

Renew the secret for your Shards’ TLS certificates.¶

Run this kubectl command to renew an existing secret that stores the sharded cluster shards’ certificates:

copy

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-cert \
  --cert=<shard-0-tls-cert> \
  --key=<shard-0-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-cert \
  --cert=<shard-1-tls-cert> \
  --key=<shard-1-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

3

Renew the secret for your config server’s TLS certificates.¶

Run this kubectl command to renew an existing secret that stores the sharded cluster config server’s certificates:

copy

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-cert \
  --cert=<config-tls-cert> \
  --key=<config-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

4

Renew the secret for your mongos server’s TLS certificates.¶

Run this kubectl command to renew an existing secret that stores the sharded cluster mongos certificates:

copy

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-cert \
  --cert=<mongos-tls-cert> \
  --key=<mongos-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

5

Renew the secret for your agents’ X.509 certificates.¶

Run this kubectl command to renew an existing secret that stores the agents’ X.509 certificates:

copy

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

Secure Client Authentication with X.509¶

General Prerequisites¶

Configure X.509 Client Authentication for a Replica Set¶

Prerequisites¶

Enable X.509 Client Authentication¶

Copy the sample replica set resource.¶

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

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

Save your replica set config file.¶

Apply your changes to your replica set deployment.¶

Track the status of your deployment.¶

Renew X.509 Certificates for a Replica Set¶

Configure kubectl to default to your namespace.¶

Renew the secret for your TLS certificates.¶

Renew the secret for your agents’ X.509 certificates.¶

Configure X.509 Client Authentication for a Sharded Cluster¶

Prerequisites¶

Enable X.509 Client Authentication¶

Copy the sample sharded cluster resource.¶

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

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

Save your sharded cluster config file.¶

Update and restart your sharded cluster deployment.¶

Track the status of your deployment.¶

Renew X.509 Certificates for a Sharded Cluster¶

Configure kubectl to default to your namespace.¶

Renew the secret for your Shards’ TLS certificates.¶

Renew the secret for your config server’s TLS certificates.¶

Renew the secret for your mongos server’s TLS certificates.¶

Renew the secret for your agents’ X.509 certificates.¶

Configure `kubectl` to default to your namespace.¶

Configure `kubectl` to default to your namespace.¶