Docs 菜单
Docs 主页
/
语言
/
Java
/
Java (Sync) 驱动程序
/
Fundamentals

身份验证机制

在此页面上

  • Overview
  • 指定身份验证机制
  • 机制
  • 默认
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-CR
  • MONGODB-AWS
  • X.509

Overview

在本指南中，您可以了解如何使用 MongoDB Community Edition 提供的每个身份验证机制对 MongoDB 进行身份验证。身份验证机制是驱动程序和 MongoDB 部署确认身份并建立信任以确保安全的过程。

可以在最新版本的 MongoDB Community Edition 中使用如下机制：

  • 默认

  • SCRAM-SHA-256

  • SCRAM-SHA-1

  • MONGODB-CR

  • MONGODB-AWS

  • x.509

要使用 Kerberos或LDAP进行身份验证，请参阅《 企业身份验证机制》指南。 有关建立与MongoDB 集群连接的更多信息，请阅读我们的连接指南。

指定身份验证机制

您可以使用以下任一方式在连接到 MongoDB 时指定身份验证机制和凭据：

  • 连接字符串

  • MongoCredential工厂方法

连接字符串（也称为连接 uri）指定如何连接到 MongoDB 集群并对其进行身份验证。

要使用连接字符串进行身份验证，请将您的设置包含在连接字符串中并将其传递给MongoClients.create()方法以实例化您的MongoClient。选择 Connection String选项卡以查看使用连接字符串进行身份验证的事务语法。

或者，您可以使用 MongoCredential 类指定身份验证详细信息。MongoCredential 类包含静态工厂方法，可构造包含身份验证机制和档案的实例。使用 MongoCredential 辅助类时，您需要在构造 MongoClient 时使用 MongoClientSettings.Builder 类来配置连接设置。选择 MongoCredential 标签页，查看使用 MongoCredential 进行身份验证的事务语法。

有关这些类和方法的更多信息，请参阅以下 API 文档：

机制

默认

默认身份验证机制设置使用以下身份验证机制之一，具体取决于您的 MongoDB Server 版本支持的版本：

  1. SCRAM-SHA-256

  2. SCRAM-SHA-1

  3. MONGODB-CR

服务器版本 3.6 及更早版本将 MONGODB-CR 作为默认机制使用。较新版本的 MongoDB Server 使用其中一种机制宣传其支持。

以下代码片段演示如何使用以下占位符指定身份验证机制：

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

  • hostname：客户端可以访问的 MongoDB 部署的网络地址

  • port：MongoDB 部署的端口号

  • authenticationDb：包含用户身份验证数据的 MongoDB database

注意

如果省略authenticationDb参数，驱动程序将使用默认的admin数据库。

选择下面的 Connection String（连接字符串）或 MongoCredential 标签页，以获取指定此身份验证机制的说明和示例代码：

若要使用连接字符串指定默认身份验证机制，请忽略该机制。用于实例化 MongoClient 的代码如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>");

若要使用 MongoCredential 类指定默认身份验证机制，请使用 createCredential() 方法。用于实例化 MongoClient 的代码如下所示：

MongoCredential credential = MongoCredential.createCredential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

如需进一步了解 MongoDB 支持的质询-响应（CR）和 Salted 质询-响应身份验证机制 （SCRAM），请参阅 MongoDB Server 手册的 SCRAM 部分。

SCRAM-SHA-256

注意

SCRAM-SHA-256 是从 MongoDB 4.0 开始使用的 MongoDB 默认身份验证方法。

SCRAM-SHA-256 是一种挑战-响应身份验证机制 (SCRAM)，使用通过 SHA-256 算法加密的用户名和密码来验证用户身份。

以下代码片段演示如何使用以下占位符指定身份验证机制：

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

  • hostname：客户端可以访问的 MongoDB 部署的网络地址

  • port：MongoDB 部署的端口号

  • authenticationDb：包含用户身份验证数据的 MongoDB database

注意

如果省略authenticationDb参数，驱动程序将使用默认的admin数据库。

选择下面的 Connection String（连接字符串）或 MongoCredential 标签页，以获取指定此身份验证机制的说明和示例代码：

若要使用连接字符串指定 SCRAM-SHA-256 身份验证机制，请在连接字符串中为 authMechanism 参数分配值 SCRAM-SHA-256。用于实例化 MongoClient 的代码如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-256");

要使用MongoCredential 类指定默认身份验证机制，请使用 createScramSha256 Credential() 方法。用于实例化MongoClient的代码类似于以下内容：

MongoCredential credential = MongoCredential.createScramSha256Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

SCRAM-SHA-1

注意

SCRAM-SHA-1 是 MongoDB 版本 3.0、3.2、3.4 和 3.6 的默认身份验证方法。

SCRAM-SHA-1 是一种盐化质询-响应机制 (SCRAM)，它使用您的用户名和密码，并通过 SHA-1 算法加密，来对您的用户进行身份验证。

以下代码片段演示如何使用以下占位符指定身份验证机制：

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

  • hostname：客户端可以访问的 MongoDB 部署的网络地址

  • port：MongoDB 部署的端口号

  • authenticationDb：包含用户身份验证数据的 MongoDB database

注意

如果省略authenticationDb参数，驱动程序将使用默认的admin数据库。

选择下面的 Connection String（连接字符串）或 MongoCredential 标签页，以获取指定此身份验证机制的说明和示例代码：

若要使用连接字符串指定 SCRAM-SHA-1 身份验证机制，请在连接字符串中为 authMechanism 参数分配值 SCRAM-SHA-1。用于实例化 MongoClient 的代码如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-1");

要使用MongoCredential 类指定默认身份验证机制，请使用 createScramSha1 Credential() 方法。用于实例化MongoClient的代码类似于以下内容：

MongoCredential credential = MongoCredential.createScramSha1Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

MONGODB-CR

MONGODB-CR 是一种挑战-响应身份验证机制，它使用您的用户名和密码 来验证您的用户。 从 MongoDB 3.6 开始，这种身份验证机制已被弃用， 从 MongoDB 4.0 开始不再支持。

您无法明确指定此方法；请参阅默认身份验证机制提供的备用机制，以使用 MONGODB-CR 进行连接。

MONGODB-AWS

注意

MONGODB-AWS 身份验证机制可用于 MongoDB Atlas 上的 MongoDB 部署。

MONGODB-AWS 身份验证机制使用 Amazon Web Services Identity and Access Management (AWS IAM) 凭证对用户进行身份验证。要了解有关配置 MongoDB Atlas 的多信息，请参阅使用 AWS IAM 角色设置无密码身份验证指南。

要指示驱动程序使用此身份验证机制，您可以指定 MONGODB-AWS 作为连接字符串中的参数或使用 MongoCredential.createAwsCredential() 工厂方法。

后续章节介绍如何指定此身份验证机制以及提供 AWS IAM 档案的各种方法。

这些部分包含使用以下占位符的代码示例：

  • awsKeyId：Amazon Web Services 访问密钥 ID 的值

  • awsSecretKey：Amazon Web Services 秘密访问密钥的值

  • atlasUri：MongoDB Atlas 部署的网络地址

  • hostname：MongoDB Atlas 部署的主机名

  • port：MongoDB Atlas 部署的端口

  • awsSessionToken：Amazon Web Services 会话令牌的值

适用于 Java 的 AWS SDK

版本 v4.8 新增。

可以使用 AWS SDK for Java v1 或 v2 来指定档案。此方法具有以下功能：

  • 获取档案的多种选项

  • 档案缓存可帮助应用程序避免速率限制

  • 与 Elastic Kubernetes Service 一起使用的凭证提供者管理。

要使用 AWS SDK for Java 进行 MONGODB-AWS 身份验证，您必须执行以下操作：

  1. 指定身份验证机制

  2. 将该 SDK 作为依赖项添加到项目中

  3. 使用档案提供程序链中的一种方法提供档案

重要

这种提供MONGODB-AWS档案的方法仅在 MongoDB Java 驱动程序 v4.8 及更高版本中可用。

要使用 MongoCredential 指定身份验证机制，请使用 MongoCredential.createAwsCredential() 工厂方法并将 MongoCredential 实例添加到您的 MongoClient，如下所示：

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
// Creates a MongoClient that receives configuration information from a MongoCredential and environment variables
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

要在连接字符串中指定身份验证机制，请将其添加为参数，如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS");

如需将 AWS SDK 作为依赖添加到项目中，请参阅以下 AWS 文档了解所需的版本：

  • 对于 AWS SDK for Java v2，请参阅设置指南。

  • 对于 AWS SDK for Java v1，请参阅入门指南。

注意

对于 AWS SDK for Java v2，Java 驱动程序当前使用software.amazon.awssdk:auth:2.18.9 依赖项进行测试。

对于 AWS SDK for Java v1，Java 驱动程序当前使用com.amazonaws:aws-java-sdk-core:1.12.337依赖项进行测试。

要提供档案，请参阅以下 AWS 文档，了解您需要的版本：

注意

如果在您的项目中同时包含适用于 Java 的 AWS SDK v1 和 v2，则必须使用 v2 方法提供凭证。

在环境中指定您的档案

您可以通过指示驱动程序使用 MONGODB-AWS 身份验证机制并设置适当的环境变量来提供 AWS IAM 档案。

要使用环境变量提供档案，必须执行以下操作：

  1. 指定身份验证机制

  2. 添加适当的环境变量

您可以使用 MongoCredential 或在连接字符串上指定身份验证机制。

要使用 MongoCredential 指定身份验证机制，请使用 MongoCredential.createAwsCredential() 工厂方法并将 MongoCredential 实例添加到您的 MongoClient，如下所示：

MongoCredential credential = MongoCredential.createAwsCredential(null, null);
// Creates a MongoClient that receives configuration information from a MongoCredential and environment variables
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

要在连接字符串中指定身份验证机制，请将其添加为参数，如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS");

以下示例展示如何通过为以下类型的身份验证设置环境变量来提供凭证：

  • 编程访问密钥

  • Web 身份提供程序

  • ECS 容器档案

  • EC2 容器档案

以下示例显示如何使用 bash 或类似的 shell 在环境变量中设置编程访问密钥：

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

如果您不需要该角色的 AWS 会话令牌，请省略包含AWS_SESSION_TOKEN的行。

您可以使用与 OpenID Connect (OIDC) 兼容的 Web 身份提供者对 Amazon Elastic Kubernetes Service (EKS) 或其他服务进行身份验证。

重要

您的项目必须包含 AWS 开发工具包 v1 或 v2 作为依赖项，才能使用 Web 身份提供商进行身份验证。

要使用 Web 身份提供程序，请创建一个包含 OIDC 令牌的文件。接下来，使用 bash 或类似的 Shell 将环境变量设置为该文件的绝对路径，如以下示例所示：

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>

要使用 ECS 容器档案进行身份验证，请使用 bash或类似 shell 在环境变量中设置 ECS 端点相对 URI，如以下示例所示：

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<your ECS endpoint>

要使用EC2 container 档案进行身份验证，请确保未设置本节中提到的任何环境变量。驱动程序从默认 IPv4 EC2 实例元数据端点而不是环境变量中获取档案。

在 MongoCredential 中指定您的档案

您可以使用 MongoCredential 实例向 MongoClient 提供您的 AWS IAM 凭证。要构造用于 MONGODB-AWS 身份验证的 MongoCredential 实例，请使用 createAwsCredential() 工厂方法。

您只能向 MongoCredential.createAwsCredential() 方法提供编程访问密钥。如果您必须提供 ECS 或 EC2 容器凭证，请按照在环境中指定凭证或适用于 Java 的 AWS SDK 中的说明进行操作。

要使用 MongoCredential 进行 MONGODB-AWS 身份验证，您必须执行以下操作：

  1. 指定身份验证机制

  2. 提供档案

要使用 MongoCredential 指定身份验证机制，请使用 MongoCredential.createAwsCredential() 工厂方法并将 MongoCredential 实例添加到您的 MongoClient，如下所示：

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
// Creates a MongoClient that receives AWS credentials from the MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

如果必须指定 AWS 会话令牌，请将其传递给 withMechanismProperty() 方法，如以下示例所示：

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()).withMechanismProperty("AWS_SESSION_TOKEN",  "<awsSessionToken>");
 // Creates a MongoClient that receives configuration information from a MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
        builder.hosts(Arrays.asList(new ServerAddress("<hostname>"))))
        .credential(credential)
        .build());

要刷新您的档案，您可以声明一个返回新档案的Supplier lambda 表达式，如以下示例所示：

Supplier<AwsCredential> awsFreshCredentialSupplier = () -> {
    // Add your code to fetch new credentials
    return new AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>");
};
// Creates a MongoCredential instance to specify the new AWS credentials
MongoCredential credential = MongoCredential.createAwsCredential(null, null)
        .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier);
// Creates a MongoClient that receives new configuration information from a MongoCredential instance
MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Collections.singletonList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

注意

如果必须在连接字符串中提供 AWS IAM 凭证，请参阅之前发布的 MONGODB-AWS 驱动程序文档。

X.509

X.509 身份验证机制使用 TLS 以及 X.509 证书对用户进行身份验证，并由客户端证书的相对标识名 (RDN) 进行标识。当您指定 X.509 身份验证机制时，服务器将使用客户端证书的标题名称对连接进行身份验证。

以下代码片段演示如何使用以下占位符指定身份验证机制：

  • hostname：客户端可以访问的 MongoDB 部署的网络地址

  • port：MongoDB 部署的端口号

  • authenticationDb：包含用户身份验证数据的 MongoDB database

注意

如果省略authenticationDb参数，驱动程序将使用默认的admin数据库。

选择下面的 Connection String（连接字符串）或 MongoCredential 标签页，以获取指定此身份验证机制的说明和示例代码：

要使用连接字符串指定 X.509 身份验证机制，请为 authMechanism 参数分配值 MONGODB-X509 并通过为 tls 参数分配 true 值来启用 TLS。用于实例化 MongoClient 的代码如下所示：

MongoClient mongoClient = MongoClients.create("mongodb://<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-X509&tls=true");

X.509MongoCredential要使用 类指定 身份验证机制，请使用 createMongoX509 Credential() 方法。此外，通过调用启用() 方法，然后在 SslSettings.Builderenabled true中将 属性设置为 区块。用于实例化MongoClient的代码类似于以下内容：

MongoCredential credential = MongoCredential.createMongoX509Credential();
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .applyToSslSettings(builder ->
            builder.enabled(true);
            )
        .credential(credential)
        .build());

有关配置应用程序以使用证书以及 TLS/SSL 选项的其他信息，请参阅我们的 TLS/SSL 指南。

后退

使用 JNDI 数据源连接到 MongoDB

来年

企业身份验证机制