Navigation

Secure Client Authentication with LDAP

MongoDB Enterprise supports:

  • Proxying authentication requests to a Lightweight Directory Access Protocol (LDAP) service.
  • Simple and SASL binding to LDAP servers. MongoDB Enterprise can bind to an LDAP server via saslauthd or through the operating system libraries.

To learn more, see the LDAP Proxy Authentication and LDAP Authorization sections in the MongoDB Server documentation.

You can use the Kubernetes Operator to configure LDAP to authenticate your client applications that connect to your MongoDB deployments. This guide describes how to configure LDAP authentication from client applications to your MongoDB deployments.

Note

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

Considerations

  • To configure LDAP in CustomResourceDefinitions, use the parameters under the spec.security.authentication.ldap and other security LDAP settings specific to the MongoDB Agent, from the Kubernetes Operator MongoDB resource specification. The procedures in this section describe the required settings and provide examples of LDAP configuration.
  • To improve security, consider configuring TLS. Encryption with TLS is optional. By default, LDAP traffic is sent as plain text. This means that username and password are exposed to network threats. Many modern directory services, such as Microsoft Active Directory, require encrypted connections. Consider using LDAP over TLS/SSL to encrypt vauthentication requests in your Kubernetes Operator MongoDB deployments.

General Prerequisites

Before you configure LDAP authentication for your MongoDB deployments, complete the following tasks:

  • Ensure that you deploy the MongoDB Enterprise database resource. MongoDB Community databases don’t support LDAP authentication.
  • Deploy the replica set or deploy the sharded cluster whose client authentication you want to secure with LDAP.

Configure LDAP 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=<metadata.namespace>
2

Create the secret for your replica set’s TLS certificate.

Run this kubectl command to create a new secret that stores the replica set’s certificate:

kubectl create secret tls <prefix>-<metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

To learn about your options for secret storage, see Configure Secret Storage.

3

Create the secret for your agent’s TLS certificate.

Run this kubectl command to create a new secret that stores the agent’s TLS certificate:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

4
5

Copy the sample replica set resource.

Change the 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.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true
16
17
18
19
20
  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
...
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 LDAP settings for your replica set resource.

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

Key Type and necessity Description Example
spec.security
boolean,
required
Set to true to enable LDAP authentication. true
string,
required
Specify the LDAP Distinguished Name to which MongoDB binds when connecting to the LDAP server. cn=admin,dc=example,dc=org
string,
required
Specify the name of the secret that contains the LDAP Bind Distinguished Name’s password with which MongoDB binds when connecting to an LDAP server. <secret-name>
string,
optional
Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <configmap-name>
string,
optional
Add the field name that stores the CA which validates the LDAP server’s TLS certificate. <configmap-key>
array of strings,
required
Specify the list of hostname:port combinations of one or more LDAP servers. For each server, use a separate line. <example.com:636>
string,
optional
Set to tls to use LDAPS (LDAP over TLS). Leave blank if your LDAP server doesn’t accept TLS. tls
string,
required

Specify the mapping that maps the username provided to mongod or mongos for authentication to an LDAP Distinguished Name (DN).

To learn more, see security.ldap.userToDNMapping and LDAP Query Templates in the MongoDB Server documentation.

<match: "(.+)",substitution: "uid={0},ou=groups,dc=example,dc=org">
spec.security
string,
required
Set to LDAP to enable authentication through LDAP. LDAP
spec.security
string,
optional

Add the <prefix> of the secret name that contains your MongoDB deployment’s TLS certificates.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

devDb
spec.security
string,
optional
Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>

The resulting configuration may look similar to the following example:

security:
 authentication:
   enabled: true
   # Enabled LDAP Authentication Mode
   modes:
     - "LDAP"
     - "SCRAM"
     # LDAP related configuration
   ldap:
   # Specify the hostname:port combination of one or
   # more LDAP servers
     servers:
       - "ldap1.example.com:636"
       - "ldap2.example.com:636"

   # Set to "tls" to use LDAP over TLS. Leave blank if
   # the LDAP server doesn't accept TLS.
   transportSecurity: "tls"

   # If TLS is enabled, add a reference to a ConfigMap that
   # contains a CA certificate that validates the LDAP server's
   # TLS certificate.
   caConfigMapRef:
     name: "<configmap-name>"
     key: "<configmap-entry-key>"

   # Specify the LDAP Distinguished Name to which
   # MongoDB binds when connecting to the LDAP server
   bindQueryUser: "cn=admin,dc=example,dc=org"

   # Specify the password with which MongoDB binds
   # when connecting to an LDAP server. This is a
   # reference to a Secret Kubernetes Object containing
   # one "password" key.
   bindQueryPasswordSecretRef:
     name: "<secret-name>"

For a full list of LDAP settings, see security settings in the Kubernetes Operator MongoDB resource specification. Also see the spec.security.authentication.agents.automationUserName setting for the MongoDB Agent user in your LDAP-enabled Kubernetes Operator deployment.

8

Configure the LDAP settings for the MongoDB Agent.

Update your MongoDB resource with security settings specific to the Agent, from the Kubernetes Operator MongoDB resource specification. The resulting configuration may look similar to the following example:

security:
  authentication:
    agents:
      automationPasswordSecretRef:
        key: automationConfigPassword
        name: automation-config-password
      automationUserName: mms-automation-agent
      clientCertificateSecretRef:
        name: agent-client-cert
      mode: LDAP
    enabled: true
    ldap:
      bindQueryPasswordSecretRef:
        name: bind-query-password
      bindQueryUser: cn=admin,dc=example,dc=org
      servers:
        - openldap.namespace.svc.cluster.local:389
      userToDNMapping: '[{match: "(.+)",substitution: "uid={0},ou=groups,dc=example,dc=org"}]'
    modes:
      - LDAP
      - SCRAM
    requireClientTLSAuthentication: false
9

Save your replica set config file.

10

Apply your changes to your replica set deployment.

Invoke the following Kubernetes command to update your replica set:

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

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 the configuration changes until the status phase achieves the Running state.

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

Configure LDAP 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=<metadata.namespace>
2

Create the secret for your sharded cluster’s TLS certificate.

Run this kubectl command to create a new secret that stores the sharded cluster’s certificate:

kubectl create secret tls <prefix>-<metadata.name>-cert \
  --cert=<sharded-cluster-tls-cert> \
  --key=<sharded-cluster-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

To learn about your options for secret storage, see Configure Secret Storage.

3

Create the secret for your agent’s TLS certificate.

Run this kubectl command to create a new secret that stores the agent’s TLS certificate:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

4

Create the ConfigMap to link your CA with your deployment.

Run this kubectl command to link your CA to your sharded cluster:

kubectl create configmap custom-ca --from-file=ca-pem
5

Copy the sample sharded cluster resource.

Change the 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.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ShardedCluster
  persistent: true
19
20
21
22
23
  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
...
6

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.

7

Configure the LDAP settings for your sharded cluster resource.

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

Key Type and necessity Description Example
spec.security
boolean,
required
Set to true to enable LDAP authentication. true
string,
required
Specify the LDAP Distinguished Name to which MongoDB binds when connecting to the LDAP server. cn=admin,dc=example,dc=org
string,
required
Specify the name of the secret that contains the LDAP Bind Distinguished Name’s password with which MongoDB binds when connecting to an LDAP server. <secret-name>
string,
optional
Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <configmap-name>
string,
optional
Add the field name that stores the CA which validates the LDAP server’s TLS certificate. <configmap-key>
array of strings,
required
Specify the list of hostname:port combinations of one or more LDAP servers. For each server, use a separate line. <example.com:636>
string,
optional
Set to tls to use LDAPS (LDAP over TLS). Leave blank if your LDAP server doesn’t accept TLS. tls
string,
required

Specify the mapping that maps the username provided to mongod or mongos for authentication to an LDAP Distinguished Name (DN).

To learn more, see security.ldap.userToDNMapping and LDAP Query Templates in the MongoDB Server documentation.

<match: "(.+)",substitution: "uid={0},ou=groups,dc=example,dc=org">
spec.security
string,
required
Set to LDAP to enable authentication through LDAP. LDAP
spec.security
string,
optional

Add the <prefix> of the secret name that contains your MongoDB deployment’s TLS certificates.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

devDb
spec.security
string,
optional
Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>

The resulting configuration may look similar to the following example:

security:
 authentication:
   enabled: true
   # Enabled LDAP Authentication Mode
   modes:
     - "LDAP"
     - "SCRAM"
     # LDAP related configuration
   ldap:
   # Specify the hostname:port combination of one or
   # more LDAP servers
     servers:
       - "ldap1.example.com:636"
       - "ldap2.example.com:636"

   # Set to "tls" to use LDAP over TLS. Leave blank if
   # the LDAP server doesn't accept TLS.
   transportSecurity: "tls"

   # If TLS is enabled, add a reference to a ConfigMap that
   # contains a CA certificate that validates the LDAP server's
   # TLS certificate.
   caConfigMapRef:
     name: "<configmap-name>"
     key: "<configmap-entry-key>"

   # Specify the LDAP Distinguished Name to which
   # MongoDB binds when connecting to the LDAP server
   bindQueryUser: "cn=admin,dc=example,dc=org"

   # Specify the password with which MongoDB binds
   # when connecting to an LDAP server. This is a
   # reference to a Secret Kubernetes Object containing
   # one "password" key.
   bindQueryPasswordSecretRef:
     name: "<secret-name>"

For a full list of LDAP settings, see security settings in the Kubernetes Operator MongoDB resource specification. Also see the spec.security.authentication.agents.automationUserName setting for the MongoDB Agent user in your LDAP-enabled Kubernetes Operator deployment.

8

Configure the LDAP settings for the MongoDB Agent.

Update your MongoDB resource with security settings specific to the Agent, from the Kubernetes Operator MongoDB resource specification. The resulting configuration may look similar to the following example:

security:
  authentication:
    agents:
      automationPasswordSecretRef:
        key: automationConfigPassword
        name: automation-config-password
      automationUserName: mms-automation-agent
      clientCertificateSecretRef:
        name: agent-client-cert
      mode: LDAP
    enabled: true
    ldap:
      bindQueryPasswordSecretRef:
        name: bind-query-password
      bindQueryUser: cn=admin,dc=example,dc=org
      servers:
        - openldap.namespace.svc.cluster.local:389
      userToDNMapping: '[{match: "(.+)",substitution: "uid={0},ou=groups,dc=example,dc=org"}]'
    modes:
      - LDAP
      - SCRAM
    requireClientTLSAuthentication: false
9

Save your sharded cluster config file.

10

Apply your changes to your sharded cluster deployment.

Invoke the following Kubernetes command to update your sharded cluster:

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

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 the configuration changes until the status phase achieves the Running state.

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