Docs Home / Node.js Driver / Authentication

X.509 Authentication MechanismX.509认证机制

Overview概述

In the X.509 authentication mechanism, the server and client use the TLS protocol to exchange X.509 public-key certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB Enterprise Advanced, and MongoDB Community Edition.X.509认证机制中,服务器和客户端使用TLS协议交换X.509公钥证书。您可以使用此机制对MongoDB Atlas、MongoDB企业高级版和MongoDB社区版进行身份验证。

Tip

X.509 Mechanism机制

To learn how to use TLS/SSL with the Node.js driver, see the Enable TLS on a Connection guide.要了解如何将TLS/SSL与Node.js驱动程序一起使用,请参阅《在连接上启用TLS》指南。

For more information about X.509 certificates, see Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments in the MongoDB Server manual.有关X.509证书的更多信息,请参阅MongoDB服务器手册中的使用X.509证书对自管理部署上的客户端进行身份验证

Code Placeholders代码占位符

The code examples on this page use the following placeholders:此页面上的代码示例使用以下占位符:

  • <cluster_url>: The network address of your MongoDB deployment.:MongoDB部署的网络地址。
  • <pem_certificate_file_path>: The path to your client PEM certificate file.:客户端PEM证书文件的路径。

To use the code examples, replace these placeholders with your own values.要使用代码示例,请将这些占位符替换为您自己的值。

Specify X.509 Authentication指定X.509身份验证

You can specify this authentication mechanism by setting the following parameters of your connection string:您可以通过设置连接字符串的以下参数来指定此身份验证机制:

  • Set the authMechanism parameter to MONGODB-X509authMechanism参数设置为MONGODB-X509
  • Set the tls parameter to truetls参数设置为true

Pass the location of your client certificate file as the value of tlsCertificateKeyFile as a parameter of the connection URI.将客户端证书文件的位置作为tlsCertificateKeyFile的值作为连接URI的参数传递。

Important

Always URI encode the certificate file path using the encodeURIComponent method to ensure it is parsed correctly.始终使用encodeURIComponent方法对证书文件路径进行URI编码,以确保其被正确解析。

const { MongoClient } = require("mongodb");

// Replace the following with values for your environment.将以下内容替换为您的环境值。
const clusterUrl = "<cluster_url>";
const clientPEMFile = encodeURIComponent("<pem_certificate_file_path>");

const authMechanism = "MONGODB-X509";

// Replace the following with your MongoDB deployment's connection string.将以下内容替换为MongoDB部署的连接字符串。
const uri =
`mongodb+srv://${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;

// Create a new MongoClient创建一个新的MongoClient
const client = new MongoClient(uri);

// Function to connect to the server连接到服务器的功能
async function run() {
try {
// Establish and verify connection建立并验证连接
await client.db("admin").command({ ping: 1 });
console.log("Connected successfully to server");
} finally {
// Ensures that the client will close when you finish/error确保客户端在您完成/出错时关闭
await client.close();
}
}
run().catch(console.dir);

TLS Options选项

The following table describes the TLS options that you can set in a connection URI.下表描述了可以在连接URI中设置的TLS选项。

Parameter Name参数名称Type类型Default Value默认值Description描述
tlsbooleanfalseSpecifies whether to enable TLS on the connection.指定是否在连接上启用TLS。
tlsInsecurebooleanfalseSpecifies whether to allow invalid certificates and mismatched hostnames. When set to true, this is equivalent to setting tlsAllowInvalidCertificates and tlsAllowInvalidHostnames to true.指定是否允许无效证书和不匹配的主机名。当设置为true时,这相当于将tlsAllowInvalidCertificatestlsAllowValidHostnames设置为true
tlsCAFilestringPath to file that contains a single or bundle of trusted certificate authorities used in a TLS connection.包含TLS连接中使用的单个或一组受信任证书颁发机构的文件路径。
tlsCertificateKeyFilestringPath to the client certificate file or the client private key file. If both are required, the two must be concatenated into a single file.客户端证书文件或客户端私钥文件的路径。如果两者都需要,则必须将两者连接成一个文件。
tlsCertificateKeyFilePasswordbuffer or stringString or buffer that contains the password to decrypt the client private key.包含用于解密客户端私钥的密码的字符串或缓冲区。
tlsAllowInvalidCertificatesbooleanfalseSpecifies whether the driver permits an invalid certificate to be used to connect.指定驱动程序是否允许使用无效证书进行连接。
tlsAllowInvalidHostnamesbooleanfalseSpecifies whether the driver raises an error when there is a mismatch between the server hostname and TLS certificate hostname.指定当服务器主机名和TLS证书主机名不匹配时,驱动程序是否会引发错误。