Database Manual / Security

x.509

MongoDB supports X.509 certificate authentication for client authentication and internal authentication of the members of replica sets and sharded clusters.MongoDB支持X.509证书身份验证，用于客户端身份验证和副本集和分片集群成员的内部身份验证。

X.509 certificate authentication requires a secure TLS/SSL connection.X.509证书身份验证需要安全的TLS/SSL连接。

Certificate Authority证书颁发机构

For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by third-party TLS vendors. 对于生产使用，MongoDB部署应该使用由证书颁发机构生成和签名的有效证书。您或组织可以生成和维护独立的证书颁发机构，或使用第三方TLS供应商生成的证书。Obtaining and managing certificates is beyond the scope of this documentation.获取和管理证书超出了本文档的范围。

Client X.509 Certificates客户端X.509证书

To authenticate to servers, clients can use X.509 certificates instead of usernames and passwords.为了向服务器进行身份验证，客户端可以使用X.509证书而不是用户名和密码。

Client Certificate Requirements客户证书要求

Client certificate requirements:客户证书要求：

  • A single Certificate Authority (CA) must issue the certificates for both the client and the server.单个证书颁发机构（CA）必须为客户端和服务器颁发证书。
  • Each unique MongoDB user must have a unique certificate.每个唯一的MongoDB用户都必须拥有一个唯一的证书。

  • The X.509 certificate must not be expired.X.509证书不得过期。

    Note

    mongod / mongos logs a warning on connection if the presented X.509 certificate expires within 30 days of the mongod/mongos host system time.如果所提供的X.509证书在mongod/mongos主机系统时间后30天内过期，则记录连接警告。

  • Client certificates must contain the following fields:客户端证书必须包含以下字段：

    keyUsage = digitalSignature
    extendedKeyUsage = clientAuth

  • At least one of the following client certificate attributes must be different than the attributes in both the net.tls.clusterFile and net.tls.certificateKeyFile server certificates:以下客户端证书属性中至少有一个必须与net.tls.clusterFile和net.tls.certificateKeyFile服务器证书中的属性不同：

    • Organization (O)
    • Organizational Unit (OU)
    • Domain Component (DC)

    Note

    You can also disable the enforceUserClusterSeparation parameter during startup to automatically disable the O/OU/DC check. This allows member certificates to authenticate as users stored in the $external database.您还可以在启动过程中禁用enforceUserClusterSeparation参数，以自动禁用O/OU/DC检查。这允许成员证书作为存储在$external数据库中的用户进行身份验证。

  • The subject of a client X.509 certificate, which contains the Distinguished Name (DN), must be different than the subjects of member X.509 certificates. 包含可分辨名称（DN）的客户端X.509证书的subject必须与成员X.509证书的subject不同。If the MongoDB deployment has tlsX509ClusterAuthDNOverride set, the client X.509 certificate's subject must not match that value.如果MongoDB部署设置了tlsX509ClusterAuthDNOverride，则客户端X.509证书的主题不得与该值匹配。

    Important

    If a client X.509 certificate's subject matches the O, OU, and DC attributes of the Member X.509 Certificate (or tlsX509ClusterAuthDNOverride, if set) exactly, the client connection is accepted, full permissions are granted, and a warning message appears in the log.如果客户端X.509证书的主题与成员X.509证书的O、OU和DC属性（或tlsX509ClusterAuthDNOverride，如果已设置）完全匹配，则接受客户端连接，授予完全权限，并在日志中显示警告消息。

    Only cluster member x509 certificates should use the same O, OU, and DC attribute combinations.只有集群成员x509证书应使用相同的O、OU和DC属性组合。

MongoDB User and $external DatabaseMongoDB用户和$external数据库

To authenticate with a client certificate, you must first add the client certificate's subject as a MongoDB user in the $external database. 要使用客户端证书进行身份验证，您必须首先将客户端证书的subject添加为$external数据库中的MongoDB用户。The $external database is the Authentication Database for the user.$external数据库是用户的身份验证数据库。

Each unique X.509 client certificate is for one MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user.每个唯一的X.509客户端证书都适用于一个MongoDB用户。您不能使用单个客户端证书对多个MongoDB用户进行身份验证。

To use Client Sessions and Causal Consistency Guarantees with $external authentication users (Kerberos, LDAP, or X.509 users), usernames cannot be greater than 10k bytes.要对$external身份验证用户（Kerberos、LDAP或X.509用户）使用客户端会话和因果一致性保证，用户名不能大于10k字节。

TLS Connection X509 Certificate Startup WarningTLS连接X509证书启动警告

Starting in MongoDB 5.0, mongod and mongos now issue a startup warning when their certificates do not include a Subject Alternative Name attribute.从MongoDB 5.0开始，当mongod和mongos的证书不包含Subject Alternative Name属性时，它们会发出启动警告。

The following platforms do not support common name validation:以下平台不支持通用名称验证：

  • iOS 13 and higheriOS 13及更高版本
  • MacOS 10.15 and higherMacOS 10.15及更高版本
  • Go 1.15 and higher达到1.15及以上

Clients using these platforms will not authenticate to MongoDB servers that use X.509 certificates whose hostnames are specified by CommonName attributes.使用这些平台的客户端将不会向使用X.509证书的MongoDB服务器进行身份验证，这些证书的主机名由CommonName属性指定。

Member X.509 Certificates成员X.509证书

For internal authentication between members of sharded clusters and replica sets, you can use X.509 certificates instead of keyfiles.对于分片集群和副本集成员之间的内部身份验证，您可以使用X.509证书而不是键文件。

Member Certificate Requirements会员证书要求

When TLS is enabled, use member certificates to verify membership to internal connections in a sharded cluster or a replica set. 启用TLS后，使用成员证书验证分片集群或副本集中内部连接的成员资格。You can configure member certificate file paths with the net.tls.clusterFile and net.tls.certificateKeyFile options. 您可以使用net.tls.clusterFile和net.tls.certificateKeyFile选项配置成员证书文件路径。Members have the following configuration requirements:成员具有以下配置要求：

  • Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:群集成员配置必须为用于身份验证的至少一个属性指定非null值。默认情况下，MongoDB接受：

    • the Organization (O)
    • the Organizational Unit (OU)
    • the Domain Component (DC)

    MongoDB verifies that entries match exactly across all member certificates. If you list multiple OU values, all certificates must use an identical list.MongoDB验证所有成员证书中的条目是否完全匹配。如果列出多个OU值，则所有证书必须使用相同的列表。

    You can specify alternative attributes to use for authentication by setting net.tls.clusterAuthX509.extensionValue.您可以通过设置net.tls.clusterAuthX509.extensionValue来指定用于身份验证的替代属性。

  • Cluster member configuration must include the same net.tls.clusterAuthX509.attributes and use matching values. 群集成员配置必须包含相同的net.tls.clusterAuthX509.attributes属性，并使用匹配的值。Attribute order doesn't matter. The following example sets O and OU, but not DC:属性顺序并不重要。以下示例设置了O和OU，但没有设置DC：

    net:
      tls:
        clusterAuthX509:
          attributes: O=MongoDB, OU=MongoDB Server

Note

If you set the enforceUserClusterSeparation parameter to false, the following behaviors apply:如果将enforceUserClusterSeparation参数设置为false，则将应用以下行为：

  • You cannot set clusterAuthMode to an option that allows X.509 or the server will not start. The server will only start if clusterAuthMode is keyFile.您不能将clusterAuthMode设置为允许X.509的选项，否则服务器将无法启动。只有当clusterAuthMode为keyFile时，服务器才会启动。
  • A client can create a user in the $external database whose O/OU/DC attributes match the server's configured attributes for cluster membership.客户端可以在$external数据库中创建一个用户，该用户的O/OU/DC属性与服务器为集群成员资格配置的属性相匹配。
  • A client presenting a member certificate can now attempt MONGODB-X509 authentication as a user in the $external database.出示成员证书的客户端现在可以作为$external数据库中的用户尝试MONGODB-X509身份验证。

To set the enforceUserClusterSeparation parameter to false, run the following command during startup:要将enforceUserClusterSeparation参数设置为false，请在启动过程中运行以下命令：

mongod --setParameter enforceUserClusterSeparation=false

The certificates have the following requirements:证书有以下要求：

  • A single Certificate Authority (CA) must issue all X.509 certificates for the members of a sharded cluster or a replica set.单个证书颁发机构（CA）必须为分片集群或副本集的成员颁发所有X.509证书。

  • At least one of the Subject Alternative Name (SAN) entries must match the server hostname used by other cluster members. When comparing SANs, MongoDB can compare either DNS names or IP addresses.至少有一个主题备选名称（SAN）条目必须与其他群集成员使用的服务器主机名匹配。在比较SAN时，MongoDB可以比较DNS名称或IP地址。

    If you don't specify subjectAltName, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per RFC2818如果不指定subjectAltName，MongoDB会比较通用名（CN）。然而，根据RFC2818，CN的这种用法已被弃用

  • If the certificate used as the certificateKeyFile includes extendedKeyUsage, the value must include both clientAuth ("TLS Web Client Authentication") and serverAuth ("TLS Web Server Authentication").如果用作certificateKeyFile的证书包括extendedKeyUsage，则该值必须同时包括clientAuth（“TLS Web客户端身份验证”）和serverAuth（“TLS Web服务器身份验证”）。

    extendedKeyUsage = clientAuth, serverAuth

  • If the certificate used as the clusterFile includes extendedKeyUsage, the value must include clientAuth.如果用作clusterFile的证书包括extendedKeyUsage，则该值必须包括clientAuth。

    extendedKeyUsage = clientAuth

MongoDB Configuration for Membership AuthenticationMongoDB成员身份验证配置

You can use TLS for internal authentication between each member of your replica set (each mongod instance) or sharded cluster (each mongod and mongos instance).您可以使用TLS在副本集的每个成员（每个mongod实例）或分片集群（每个mongod和mongos实例）之间进行内部身份验证。

To use TLS for internal authentication, use the following settings:要使用TLS进行内部身份验证，请使用以下设置：

Important

If you set --tlsMode to any value other than disabled, MongoDB uses the certificate specified in net.tls.certificateKeyFile for both server and client authentication in internal replica set connections. 如果将--tlsMode设置为disabled以外的任何值，MongoDB将在内部副本集连接中使用net.tls.certificateKeyFile中指定的证书进行服务器和客户端身份验证。This certificate setting applies regardless of whether you set security.clusterAuthMode to X.509.无论您是否将security.clusterAuthMode设置为X.509，此证书设置都适用。

mongod and mongos instances use their certificate key files to prove their identity to clients, but certificate key files can also be used for membership authentication. mongod和mongos实例使用其证书键文件向客户端证明其身份，但证书键文件也可用于成员身份验证。If you do not specify a cluster file, members use their certificate key files for membership authentication. 如果不指定群集文件，成员将使用其证书键文件进行成员身份验证。Specify the certificate key file with net.tls.certificateKeyFile or --tlsCertificateKeyFile.使用net.tls.certificateKeyFile或--tlsCertificateKeyFile指定证书键文件。

To use the certificate key file for both client authentication and membership authentication, the certificate must either:要将证书键文件用于客户端身份验证和成员身份验证，证书必须：

  • Omit 省略extendedKeyUsage or或
  • Specify 指定extendedKeyUsage = serverAuth, clientAuth