Secure Client Authentication with LDAP
On this page
- Considerations
- General Prerequisites
- Configure LDAP Client Authentication for a Replica Set
- Copy the sample replica set resource.
- Paste the copied example section into your existing replica set resource.
- Configure the LDAP settings for your replica set resource.
- Configure the LDAP settings for the MongoDB Agent.
- Save your replica set config file.
- Apply your changes to your replica set deployment.
- Track the status of your deployment.
- Configure LDAP Client Authentication for a Sharded Cluster
- Copy the sample sharded cluster resource.
- Paste the copied example section into your existing sharded cluster resource.
- Configure the LDAP settings for your sharded cluster resource.
- Configure the LDAP settings for the MongoDB Agent.
- Save your sharded cluster config file.
- Apply your changes to your sharded cluster deployment.
- Track the status of your deployment.
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
saslauthdor 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.ldapand 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 deploying a TLS-encrypted replica set or a TLS-encrypted sharded cluster. 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 authentication 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
Copy the sample replica set resource.
Change the settings of this YAML file to match your desired replica set configuration.
1 2 apiVersion: mongodb.com/v1 3 kind: MongoDB 4 metadata: 5 name: <my-replica-set> 6 spec: 7 members: 3 8 version: "4.2.2-ent" 9 opsManager: 10 configMapRef: 11 # Must match metadata.name in ConfigMap file 12 name: <configMap.metadata.name> 13 credentials: <mycredentials> 14 type: ReplicaSet 15 persistent: true
16 security: 17 tls: 18 ca: <custom-ca> 19 certsSecretPrefix: <prefix> 20 ...
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.
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 |
spec.security | string, required | Specify the LDAP Distinguished Name to which MongoDB binds when
connecting to the LDAP server. | cn=admin,dc=example,dc=org |
spec.security | 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> |
spec.security | string, optional | Add the ConfigMap's name that stores the custom CA
that you used to sign your deployment's TLS certificates. | <configmap-name> |
spec.security | string, optional | Add the field name that stores the CA which validates the
LDAP server's TLS certificate. | <configmap-key> |
spec.security | 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> |
spec.security | string, optional | Set to tls to use LDAPS (LDAP over TLS). Leave blank if
your LDAP server doesn't accept TLS. You must enable TLS when you
deploy the database resource to use this setting. | tls |
spec.security | string, required | Specify the mapping that maps the username provided to
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 |
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. You must enable TLS when you deploy the database resource to use this setting. 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.
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
Save your replica set config file.
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
Track the status of your deployment.
To check the status of your MongoDB resource, use the following
command:
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.
Configure LDAP Client Authentication for a Sharded Cluster
Copy the sample sharded cluster resource.
Change the settings of this YAML file to match your desired sharded cluster configuration.
1 2 apiVersion: mongodb.com/v1 3 kind: MongoDB 4 metadata: 5 name: <my-sharded-cluster> 6 spec: 7 shardCount: 2 8 mongodsPerShardCount: 3 9 mongosCount: 2 10 configServerCount: 3 11 version: "4.2.2-ent" 12 opsManager: 13 configMapRef: 14 name: <configMap.metadata.name> 15 # Must match metadata.name in ConfigMap file 16 credentials: <mycredentials> 17 type: ShardedCluster 18 persistent: true
19 security: 20 tls: 21 ca: <custom-ca> 22 certsSecretPrefix: <prefix> 23 ...
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.
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 |
spec.security | string, required | Specify the LDAP Distinguished Name to which MongoDB binds when
connecting to the LDAP server. | cn=admin,dc=example,dc=org |
spec.security | 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> |
spec.security | string, optional | Add the ConfigMap's name that stores the custom CA
that you used to sign your deployment's TLS certificates. | <configmap-name> |
spec.security | string, optional | Add the field name that stores the CA which validates the
LDAP server's TLS certificate. | <configmap-key> |
spec.security | 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> |
spec.security | string, optional | Set to tls to use LDAPS (LDAP over TLS). Leave blank if
your LDAP server doesn't accept TLS. You must enable TLS when you
deploy the database resource to use this setting. | tls |
spec.security | string, required | Specify the mapping that maps the username provided to
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 |
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. You must enable TLS when you deploy the database resource to use this setting. 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.
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
Save your sharded cluster config file.
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
Track the status of your deployment.
To check the status of your MongoDB resource, use the following
command:
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.