启用和配置 TLS

在此页面上

Overview

启用 TLS
配置证书
参考证书
更多信息

Overview

在本指南中，您可以了解如何使用 TLS 协议保护与 MongoDB 部署的连接。要将连接配置为使用 TLS，请启用 TLS 选项，并可选择在应用程序的 config/database.php文件中提供用于验证的证书。

提示

要学习；了解有关 TLS 的更多信息，请参阅有关传输层安全性的维基百科条目。

启用 TLS

在应用程序的config/database.php文件中，您可以通过以下方式之一在与 MongoDB 部署的连接上启用 TLS：

在连接字符串中将 tls 选项设置为 true
在mongodb连接条目的options属性中将tls选项设置为true

从以下 Connection String和Connection Options标签页中选择，查看相应的代码示例：

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb://<hostname>:<port>/?tls=true',
        'database' => 'myDB',
    ]
]

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => '<connection string>',
        'database' => 'myDB',
        'options'  => [
            'tls' => true,
        ],
    ]
]

要查看连接选项的完整列表，请参阅连接选项。

注意

如果您的连接字符串通过包含mongodb+srv前缀来使用 DNS SRV 记录，则默认情况下会对您的连接启用 TLS。

配置证书

要成功发起 TLS请求，您的应用程序可能需要提供加密证书来证明其身份。应用程序的证书必须存储为 PEM 文件，才能在连接时启用TLS。

重要

对于生产使用，我们建议您的 MongoDB 部署使用由同一证书颁发机构生成和签名的有效证书。对于测试，您的部署可以使用自签名证书。

以下列表描述了客户端可以提供的用于建立启用 TLS 的连接的组件：

TLS 组件	说明
证书颁发机构 (CA)	建立 TLS 连接时要信任的一个或多个证书颁发机构。您可以将此文件的路径传递给`tlsCAFile`选项。
客户端证书	数字证书，允许服务器验证应用程序的身份，以建立加密的网络连接。您可以将此文件的路径传递给`tlsCertificateKeyFile`选项。
证书密钥	客户端证书私钥文件。此密钥通常包含在证书文件中。如果必须提供此项，则应将证书和密钥合并在一个文件中，并将该文件传递给`tlsCertificateKeyFile`选项。
密码	用于解密客户端私钥（如果已加密）的密码。您可以将此文件的路径传递给`tlsCertificateKeyFilePassword`选项。

参考证书

如有必要，您必须在配置mongodb连接时引用证书，以便服务器可以在客户端连接之前验证证书。

我们建议您在连接配置的 options 属性中（而不是在连接string中）引用证书并设置其他 TLS 选项。这提高了应用程序中代码的可读性。

在options属性中设置以下选项以引用您的证书：

tlsCAFile
tlsCertificateKeyFile
tlsCertificateKeyFilePassword

注意

出于测试目的，您可以将以下选项设置为true以禁用验证：

tlsAllowInvalidCertificates
tlsAllowInvalidHostnames

或者，您可以将tlsInsecure选项设置为true ，以隐式设置上述两个选项。

在生产环境中指定这些选项可能会使应用程序不安全。要了解更多信息，请参阅 MongoDB Server手册中的连接选项参考。

以下示例配置了启用 TLS 的连接：

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => '<connection string>',
        'database' => 'myDB',
        'options'  => [
            'tls' => true,
            'tlsCAFile' => '<path to CA certificate>',
            'tlsCertificateKeyFile' => '<path to private client certificate>',
            'tlsCertificateKeyFilePassword' => '<path to client key passphrase>',
        ]
    ]
]