身份验证机制

在本页中

概述

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-X509
MONGODB-AWS
MongoClient凭据
环境变量
共享凭据文件
AWS配置文件
AssumeRole请求
AssumeRoleWithWebIdentity
ECS容器或EC2实例
API文档

概述

本指南描述了您可以在PyMongo中使用的用户身份验证机制。

重要

百分编码

您必须百分号编码在将用户名和密码包含在 MongoDB URI 中之前，对它们进行百分号编码。quote_plus() 方法，可在 urllib.parse 模块中使用，是执行此任务的一种方法。例如，调用 quote_plus("and / or") 返回字符串 and+%2F+or。

在将用户名和密码作为参数传递给 MongoClient 时，不要对它们进行百分号编码。

SCRAM-SHA-256

SCRAM-SHA-256，由RFC 7677定义，是MongoDB v4.0或更高版本部署上的默认认证机制。

要使用此机制进行认证，请设置以下连接选项

db_username：用于认证的用户名。在将其包含在连接URI中之前，请对该值进行百分号编码。
db_password：用于认证的密码。在将其包含在连接URI中之前，请对该值进行百分号编码。
authSource：要认证的MongoDB数据库。默认情况下，PyMongo在连接URI中包含数据库时认证该数据库。如果不包含，则认证admin数据库。
authMechanism：设置为SCRAM-SHA-256。

您可以通过两种方式设置这些选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             username="<db_username>",
                             password="<db_password>",
                             authSource="<authentication database>",
                             authMechanism="SCRAM-SHA-256")

uri = ("mongodb://<percent-encoded db_username>:<percent-encoded db_password>"
       "@<hostname>:<port>/?"
       "authSource=<authentication database>"
       "&authMechanism=SCRAM-SHA-256")
client = pymongo.MongoClient(uri)

SCRAM-SHA-1

SCRAM-SHA-1，如由RFC 5802定义，是MongoDB v3.6版本部署中的默认身份验证机制。

要使用此机制进行认证，请设置以下连接选项

db_username：用于认证的用户名。在将其包含在连接URI中之前，请对该值进行百分号编码。
db_password：用于认证的密码。在将其包含在连接URI中之前，请对该值进行百分号编码。
authSource：要验证的MongoDB数据库。默认情况下，PyMongo验证的是admin数据库。
authMechanism：设置为"SCRAM-SHA-1"。

您可以通过两种方式设置这些选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             username="<db_username>",
                             password="<db_password>",
                             authSource="<authentication database>",
                             authMechanism="SCRAM-SHA-1")

uri = ("mongodb://<percent-encoded db_username>:<percent-encoded db_password>"
       "@<hostname>:<port>/?"
       "authSource=<authentication database>"
       "&authMechanism=SCRAM-SHA-1")
client = pymongo.MongoClient(uri)

MONGODB-X509

如果您启用TLS，在TLS握手过程中，PyMongo可以提供X.509客户端证书以证明其身份。MONGODB-X509身份验证机制使用此证书来验证客户端。

要使用此机制进行认证，请设置以下连接选项

tls：设置为True。
tlsCertificateKeyFile：包含您的客户端证书和私钥的.pem文件路径。
authMechanism：设置为"MONGODB-X509"。

您可以通过两种方式设置这些选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             tls=True,
                             tlsCertificateKeyFile="/path/to/client.pem",
                             authMechanism="MONGODB-X509")

uri = ("mongodb://<hostname>:<port>/?"
       "tls=true"
       "&tlsCertificateKeyFile=path/to/client.pem"
       "&authMechanism=MONGODB-X509")
client = pymongo.MongoClient(uri)

MONGODB-AWS

重要

MONGODB-AWS认证机制需要MongoDB v4.4或更高版本。

MONGODB-AWS认证机制使用AWS IAM（亚马逊云服务身份和访问管理）或AWS Lambda凭证来验证您的应用程序。要使用MONGODB-AWS进行认证，您必须安装带有aws选项的PyMongo，如下所示示例

python -m pip install pymongo[aws]

PyMongo使用Boto3，Python的AWS SDK，来处理凭证。Boto3尝试按以下顺序从以下来源检索AWS凭证

传递给MongoClient构造函数的命名参数或连接URI中的参数
环境变量
共享凭证文件
AWS配置文件
对AWS安全令牌服务（STS）的AssumeRole请求
对AWS STS的AssumeRoleWithWebIdentity请求
配置了IAM角色的Amazon EC2实例上的实例元数据服务

以下各节描述了如何使用PyMongo从这些来源检索凭证并使用它们来验证您的应用程序。

`MongoClient`凭证

首先，PyMongo检查您是否已将AWS凭证传递给MongoClient构造函数，无论是作为命名参数还是作为连接URI的一部分。要将凭证传递给MongoClient，设置以下连接选项

username：用于验证的AWS IAM访问密钥ID。在将其包含在连接URI之前，对此值进行百分编码。
password：AWS IAM秘密访问密钥。在将其包含在连接URI之前，对此值进行百分编码。
authMechanism：设置为"MONGODB-AWS"。

您可以通过两种方式设置这些选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

client = pymongo.MongoClient("mongodb://@<hostname>:<port>",
                             username="<AWS IAM access key ID>",
                             password="<AWS IAM secret access key>",
                             authMechanism="MONGODB-AWS")

uri = ("mongodb://<percent-encoded AWS IAM access key ID>:"
       "<percent-encoded AWS IAM secret access key>"
       "@<hostname>:<port>/?"
       "&authMechanism=MONGODB-AWS")
client = pymongo.MongoClient(uri)

环境变量

如果您在构建 MongoClient 对象时没有提供用户名和密码，PyMongo 会尝试从以下环境变量中检索 AWS 凭据

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

要使用这些环境变量来验证您的应用程序，首先将它们设置为用于验证所需的 AWS IAM 值，如下面的代码示例所示

export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
export AWS_SESSION_TOKEN=<AWS session token>

重要

不要对这些环境变量的值进行百分号编码。

设置这些环境变量后，将连接选项 authMechanism 设置为 "MONGODB-AWS"。您可以通过两种方式设置此选项：通过将参数传递给 MongoClient 构造函数或在您的连接字符串中设置参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             authMechanism="MONGODB-AWS")

uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
client = pymongo.MongoClient(uri)

提示

AWS Lambda

AWS Lambda 运行时可以在初始化期间自动设置这些环境变量。有关在 AWS Lambda 环境中使用环境变量的更多信息，请参阅 AWS 文档中的使用 Lambda 环境变量。

共享凭证文件

如果PyMongo在前面的环境变量中找不到AWS凭证，它将尝试从共享凭证文件中读取它们。

要使用共享凭证文件来验证您的应用程序，请确保文件存在于您的环境中，并且配置正确。有关创建共享凭证文件的说明，请参阅Boto3文档中的凭证和AWS文档中的配置。

创建共享凭证文件后，将连接选项authMechanism设置为"MONGODB-AWS"。您可以通过两种方式设置此选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             authMechanism="MONGODB-AWS")

uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
client = pymongo.MongoClient(uri)

提示

要防止PyMongo使用共享凭证文件进行认证，执行以下操作之一

将终端中的环境变量 AWS_SHARED_CREDENTIALS_FILE 设置为 ""。
在您的脚本或应用程序中添加 os.environ["AWS_SHARED_CREDENTIALS_FILE"] = ""。
创建一个专门用于您的 MongoDB 凭证的 AWS 配置文件。将环境变量 AWS_PROFILE 设置为您创建的配置文件名称。

AWS 配置文件

如果 PyMongo 在共享凭证文件中找不到凭证，它会尝试从 AWS 配置文件中读取它们。

要使用 AWS 配置文件对您的应用程序进行身份验证，请确保该文件存在于您的环境中，并且配置正确。有关如何创建 AWS 配置文件的说明，请参阅 Boto3 文档中的凭据以及 AWS 文档中的配置。

创建配置文件后，将连接选项 authMechanism 设置为 "MONGODB-AWS"。您可以通过两种方式设置此选项：通过将参数传递给 MongoClient 构造函数或在连接字符串参数中。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             authMechanism="MONGODB-AWS")

uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
client = pymongo.MongoClient(uri)

假设角色请求

您可以选择不将AWS凭据存储在AWS配置文件中，而是指导PyMongo向AWS STS端点发送一个AssumeRole请求。此请求将返回临时凭据，您的应用程序可以使用这些凭据进行身份验证。

要使用由AssumeRole请求返回的临时AWS IAM凭据进行身份验证，请确保您的环境中存在AWS配置文件且已正确配置。有关如何创建和配置AWS配置文件的说明，请参阅Boto3文档中的Credentials和AWS文档中的Configuration。

创建配置文件后，设置以下连接选项

username：由AssumeRole请求返回的AWS IAM访问密钥ID。在将其包含在连接URI中之前，请对该值进行百分号编码。
password：由AssumeRole请求返回的AWS IAM密钥访问密钥。在将其包含在连接URI中之前，请对该值进行百分号编码。
authMechanismProperties：设置为AWS_SESSION_TOKEN:和由AssumeRole请求返回的AWS会话令牌。
authMechanism：设置为"MONGODB-AWS"。

您可以通过两种方式设置这些选项：通过将参数传递给MongoClient构造函数或通过连接字符串中的参数。

注意

如果你的 authMechanismProperties 值包含逗号，你必须使用 MongoClient 构造函数来设置你的身份验证选项。

client = pymongo.MongoClient("mongodb://@<hostname>:<port>",
                             username="<AWS IAM access key ID>",
                             password="<AWS IAM secret access key>",
                             authMechanismProperties="AWS_SESSION_TOKEN:<AWS session token>",
                             authMechanism="MONGODB-AWS")

uri = ("mongodb://<percent-encoded AWS IAM access key ID>:"
       "<percent-encoded AWS IAM secret access key>"
       "@<hostname>:<port>/?"
       "authMechanismProperties=AWS_SESSION_TOKEN:<AWS session token>"
       "&authMechanism=MONGODB-AWS")
client = pymongo.MongoClient(uri)

有关使用 AssumeRole 请求进行应用程序身份验证的更多信息，请参阅以下 AWS 文档

AssumeRoleWithWebIdentity

重要

你的应用程序必须使用 pymongo_auth_aws v1.1.0 或更高版本以支持 EKS。

如果你的应用程序从 OpenID Connect (OIDC) 身份提供者验证你的 EKS 集群用户，PyMongo 可以发出一个 AssumeRoleWithWebIdentity 请求，以将 OIDC 令牌交换为应用程序的临时 AWS 凭证。

为了使用 AssumeRoleWithWebIdentity 请求返回的临时 AWS IAM 凭证进行身份验证，请确保你的环境中存在 AWS 配置文件并且配置正确。有关创建和配置 AWS 配置文件的说明，请参阅 Boto3 文档中的 Credentials 和 AWS 文档中的 Configuration。

在您为 AssumeRoleWithWebIdentity 请求配置环境后，将连接选项 authMechanism 设置为 "MONGODB-AWS"。您可以通过两种方式设置此选项：通过将参数传递给 MongoClient 构造函数或在您的连接字符串中设置参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             authMechanism="MONGODB-AWS")

uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
client = pymongo.MongoClient(uri)

有关使用 AssumeRoleWithWebIdentity 请求对您的应用程序进行身份验证的更多信息，请参阅以下 AWS 文档

ECS 容器或 EC2 实例

如果您的应用程序在弹性容器服务（ECS）容器中的 Amazon Elastic Cloud Compute（EC2）实例上运行，PyMongo 可以自动从 ECS 端点检索临时 AWS 凭据。

要在 EC2 实例内部使用临时凭据，将连接选项 authMechanism 设置为 "MONGODB-AWS"。您可以通过两种方式设置此选项：通过将参数传递给 MongoClient 构造函数或在您的连接字符串中设置参数。

client = pymongo.MongoClient("mongodb://<hostname>:<port>",
                             authMechanism="MONGODB-AWS")

uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
client = pymongo.MongoClient(uri)

API 文档

有关在 PyMongo 中对您的应用程序进行身份验证的更多信息，请参阅以下 API 文档

MongoClient

安全性

企业身份验证

概述

重要

百分编码

SCRAM-SHA-256

SCRAM-SHA-1

MONGODB-X509

MONGODB-AWS

重要

MongoClient凭证

环境变量

重要

提示

AWS Lambda

共享凭证文件

提示

AWS 配置文件

假设角色请求

注意

AssumeRoleWithWebIdentity

重要

ECS 容器或 EC2 实例

API 文档

`MongoClient`凭证