Database Manual / Security / x.509

Use X.509 Certificates to Authenticate Clients on Self-Managed Deployments使用X.509证书对自我管理部署上的客户端进行身份验证

The following procedure sets up X.509 certificate authentication for client authentication on a standalone mongod instance. This is also known as Mutual TLS or mTLS.以下过程为独立mongod实例上的客户端身份验证设置X.509证书身份验证。这也被称为双向TLS或mTLS。

To use X.509 authentication for replica sets or sharded clusters, see Use X.509 Certificates for Membership Authentication with Self-Managed MongoDB.要对副本集或分片集群使用X.509身份验证，请参阅使用X.509证书进行自我管理MongoDB的成员身份验证。

Prerequisites先决条件

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, in particular X.509 certificates, and Certificate Authority is beyond the scope of this document. This tutorial assumes prior knowledge of TLS/SSL as well as access to valid X.509 certificates.TLS/SSL、PKI（公钥基础设施）证书（特别是X.509证书）和证书颁发机构的完整描述超出了本文的范围。本教程假设您具备TLS/SSL的先验知识以及有效X.509证书的访问权限。

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. Obtaining and managing certificates is beyond the scope of this documentation.对于生产使用，MongoDB部署应该使用由证书颁发机构生成和签名的有效证书。您或组织可以生成和维护独立的证书颁发机构，或使用第三方TLS供应商生成的证书。获取和管理证书超出了本文档的范围。

To use X.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.要使用X.509身份验证，必须指定--tlsCAFile或net.tls.CAFile，除非您使用的是--tlsCertificateSelector或--nettlscertificateSelector。

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

You must have valid X.509 certificates. The client X.509 certificates must meet the client certificate requirements.您必须拥有有效的X.509证书。客户端X.509证书必须满足客户端证书要求。

If you specify --tlsAllowInvalidCertificates or net.tls.allowInvalidCertificates: true, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication.如果指定--tlsAllowInvalidCertificates或net.tls.allowInvalidCertificates: true，则无效证书仅足以建立TLS连接，但不足以进行身份验证。

Procedure过程

1

Deploy with X.509 Authentication使用X.509身份验证进行部署

Command Options命令选项

You can configure a mongod instance for X.509 authentication from the command-line.您可以从命令行配置mongod实例进行X.509身份验证。

To configure a standalone mongod instance, run the following command:要配置独立的mongod实例，请运行以下命令：

mongod --tlsMode requireTLS \
    --tlsCertificateKeyFile <path to TLS/SSL certificate and key PEM file> \
    --tlsCAFile <path to root CA PEM file> --bind_ip <hostnames>

Include additional options as required for your configuration.根据配置要求，包括其他选项。

The X.509 configuration requires:X.509配置要求：

Option选项Notes备注
--tlsModeSpecify requireTLS.指定requireTLS。
--tlsCertificateKeyFileSpecify the instance's X.509 certificate to present to clients.指定要呈现给客户端的实例X.509证书。
--tlsCAFileSpecify the Certificate Authority file to verify the certificates presented to the instance.指定证书颁发机构文件以验证提供给实例的证书。
Configuration File配置文件

You can configure a mongod for X.509 authentication in the configuration file.您可以在配置文件中为X.509身份验证配置mongod。

To configure a standalone mongod instance, add the following configuration options to your configuration file:要配置独立的mongod实例，请在配置文件中添加以下配置选项：

net:
   tls:
      mode: requireTLS
      certificateKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Include additional options as required for your configuration.根据配置要求，包括其他选项。

The X.509 configuration requires:X.509配置要求：

Option选项Notes备注
net.tls.modeSpecify requireTLS.指定requireTLS。
net.tls.certificateKeyFileSpecify the instance's X.509 certificate to present to clients.指定要呈现给客户端的实例X.509证书。
net.tls.CAFileSpecify the Certificate Authority file to verify the certificates presented to the instance.指定证书颁发机构文件以验证提供给实例的证书。

To set up X.509 authentication for replica sets or sharded clusters, see Use X.509 Certificates for Membership Authentication with Self-Managed MongoDB.要为副本集或分片集群设置X.509身份验证，请参阅使用X.509证书进行自我管理MongoDB的成员身份验证。

2

Add X.509 Certificate subject as a User将X.509证书subject添加为用户

To authenticate with a client certificate, you must first add the value of the subject from the client certificate as a MongoDB user to the $external database. 要使用客户端证书进行身份验证，您必须首先将客户端证书中的subject值作为MongoDB用户添加到$external数据库中。Each unique X.509 client certificate corresponds to a single MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user.每个唯一的X.509客户端证书对应一个MongoDB用户。您不能使用单个客户端证书对多个MongoDB用户进行身份验证。

Note

Username Requirements用户名要求

  1. You can retrieve the RFC2253 formatted subject from the client certificate with the following command:您可以使用以下命令从客户端证书中检索RFC2253格式的subject：

    openssl x509 -in <pathToClientPEM> -inform PEM -subject -nameopt RFC2253

    The command returns the subject string and the certificate:该命令返回subject字符串和证书：

    subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry
    -----BEGIN CERTIFICATE-----
    # ...
    -----END CERTIFICATE-----

  2. Add the RFC2253 compliant value of the subject as a user. Omit spaces as needed.将subject的RFC2253兼容值添加为用户。根据需要省略空格。

    The following example adds a user and grants the user readWrite role in the test database and the userAdminAnyDatabase role:以下示例添加了一个用户，并在test数据库中授予用户readWrite角色和userAdminAnyDatabase角色：

    db.getSiblingDB("$external").runCommand(
      {
        createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry",
        roles: [
             { role: "readWrite", db: "test" },
             { role: "userAdminAnyDatabase", db: "admin" }
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }
    )

    See Manage Users and Roles on Self-Managed Deployments for details on adding a user with roles.有关添加具有角色的用户的详细信息，请参阅自我管理部署上的管理用户和角色。

3

Authenticate with a X.509 Certificate使用X.509证书进行身份验证

After you have added the X.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate:将X.509客户端证书主体添加为相应的MongoDB用户后，您可以使用客户端证书进行身份验证：

Connection String连接字符串

To authenticate during connection, run the following command:要在连接期间进行身份验证，请运行以下命令：

mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \
    --tlsCAFile <path to root CA PEM file> \
    --authenticationDatabase '$external' \
    --authenticationMechanism MONGODB-X509
Option选项Notes备注
--tls
--tlsCertificateKeyFileSpecify the client's X.509 file.指定客户端的X.509文件。
--tlsCAFileSpecify the Certificate Authority file to verify the certificate presented by the mongod instance.指定证书颁发机构文件以验证mongod实例提供的证书。
--authenticationDatabaseSpecify '$external'.指定'$external'。
--authenticationMechanismSpecify MONGODB-X509.指定MONGODB-X509。
Authenticate after Connection连接后进行身份验证

You can connect without authentication and use the db.auth() method to authenticate after connection.您可以在不进行身份验证的情况下进行连接，并在连接后使用db.auth()方法进行身份验证。

For example, if using mongosh,例如如果使用mongosh，

  1. Connect mongosh to the mongod:将mongosh连接到mongod：

    mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \
        --tlsCAFile <path to root CA PEM file>
    Option选项Notes备注
    --tls
    --tlsCertificateKeyFileSpecify the client's X.509 file.指定客户端的X.509文件。
    --tlsCAFileSpecify the Certificate Authority file to verify the certificate presented by the mongod or mongos instance.指定证书颁发机构文件以验证mongod或mongos实例提供的证书。

  2. To authenticate, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509".要进行身份验证，请使用$external数据库中的db.auth()方法。对于机制字段，指定"MONGODB-X509"。

    db.getSiblingDB("$external").auth(
      {
        mechanism: "MONGODB-X509"
      }
    )

Next Steps后续步骤

To use X.509 authentication for replica sets or sharded clusters, see Use X.509 Certificates for Membership Authentication with Self-Managed MongoDB.要对副本集或分片集群使用X.509身份验证，请参阅使用X.509证书进行自我管理MongoDB的成员身份验证。