文档菜单
文档首页
/
语言
/
Java
/
Java 同步驱动器
/
基础知识

身份验证机制

本页内容

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

概述

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

您可以使用MongoDB社区版最新版本中提供的以下机制

  • 默认

  • SCRAM-SHA-256

  • SCRAM-SHA-1

  • MONGODB-CR

  • MONGODB-AWS

  • X.509

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

指定身份验证机制

您可以通过以下任一方式连接到MongoDB并指定身份验证机制和凭证：

  • 连接字符串

  • MongoCredential 工厂方法

连接字符串（也称为连接URI）指定了连接和身份验证到您的MongoDB集群的方式。

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

或者，您可以使用 MongoCredential 类来指定您的身份验证详细信息。MongoCredential 类包含静态工厂方法，这些方法构建包含您的身份验证机制和凭据的实例。当您使用 MongoCredential 辅助类时，您需要在构建 MongoClient 时使用 MongoClientSettings.Builder 类来配置您的连接设置。选择 MongoCredential 选项卡以查看使用 MongoCredential 进行身份验证的语法。

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

机制

默认

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

  1. SCRAM-SHA-256

  2. SCRAM-SHA-1

  3. MONGODB-CR

服务器版本 3.6 及更早版本使用 MONGODB-CR 作为默认机制。MongoDB 服务器的新版本使用它们宣传支持的机制之一。

以下代码示例显示了如何指定身份验证机制，使用以下占位符

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

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

  • port：您的 MongoDB 部署的端口号

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

注意

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

选择下方的 连接字符串 或 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）和加盐挑战-响应认证机制（SCRAM）的更多信息，请参阅MongoDB服务器手册的 SCRAM 部分。

SCRAM-SHA-256

注意

SCRAM-SHA-256 是从MongoDB 4.0开始默认的认证方法。

SCRAM-SHA-256 是一种加盐挑战-响应认证机制（SCRAM），它使用您的用户名和密码（使用 SHA-256 算法加密）来认证您的用户。

以下代码示例显示了如何指定身份验证机制，使用以下占位符

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

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

  • port：您的 MongoDB 部署的端口号

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

注意

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

选择下方的 连接字符串 或 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 类指定默认认证机制，请使用 createScramSha256Credential() 方法。创建 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 是一种使用您的用户名和密码（用 SHA-1 算法加密）进行身份验证的盐值挑战-响应机制 (SCRAM)。

以下代码示例显示了如何指定身份验证机制，使用以下占位符

  • username：您的 MongoDB 用户名

  • password：您的 MongoDB 用户的密码

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

  • port：您的 MongoDB 部署的端口号

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

注意

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

选择下方的 连接字符串 或 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 类指定默认身份验证机制，请使用 createScramSha1Credential() 方法。创建 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：您的 AWS 访问密钥 ID 的值

  • awsSecretKey：您的 AWS 密钥访问密钥的值

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

  • hostname：您的 MongoDB Atlas 部署的主机名

  • port：您的 MongoDB Atlas 部署的端口

  • awsSessionToken：您的 AWS 会话令牌的值

AWS SDK for Java

新内容在版本v4.8.

您可以使用AWS SDK for Java v1或v2中的一个来指定您的凭证。此方法提供以下功能

  • 多种获取凭证的选项

  • 凭证缓存，帮助您的应用程序避免速率限制

  • 凭证提供者管理，用于与弹性Kubernetes服务。

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

  1. 指定认证机制

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

  3. 使用凭证提供者链中的方法之一提供您的凭证

重要

此提供MONGODB-AWS凭证的方法仅在MongoDB Java Driver 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，Java 驱动当前使用 software.amazon.awssdk:auth:2.18.9 依赖项进行测试。

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

要提供您的凭证，请参阅以下 AWS 文档以获取您所需的版本

注意

如果你的项目中同时包含 AWS SDK for Java 的 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)的网络身份提供者来验证Amazon Elastic Kubernetes Service (EKS)或其他服务。

重要

您的项目必须将AWS SDK的v1或v2作为依赖项，以使用网络身份提供者进行身份验证。

要使用网络身份提供者，创建一个包含您的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容器凭据进行身份验证，请确保本节中提到的任何环境变量都没有设置。驱动程序将从默认IPv4 EC2实例元数据端点获取凭据，而不是从环境变量中获取。

在MongoCredential中指定您的凭据

您可以通过使用MongoCredential实例将AWS IAM凭据提供给MongoClient。为了构建用于MONGODB-AWS身份验证的MongoCredential实例，请使用createAwsCredential()工厂方法。

您可以为MongoCredential.createAwsCredential()方法提供仅程序访问密钥。如果您必须提供ECS或EC2容器凭据，请使用在环境中指定您的凭据或AWS SDK for Java。中的说明。

要使用 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证书来验证用户身份，用户身份通过客户端证书的相对区分名称（RDNs）进行识别。当指定X.509身份验证机制时，服务器将使用客户端证书的主题名称进行连接验证。

以下代码示例显示了如何指定身份验证机制，使用以下占位符

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

  • port：您的 MongoDB 部署的端口号

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

注意

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

选择下方的 连接字符串 或 MongoCredential 选项卡，以获取指定此认证机制的说明和示例代码。

要使用连接字符串指定X.509身份验证机制，将authMechanism参数设置为MONGODB-X509，并通过将tls参数设置为true来启用TLS。实例化MongoClient的代码类似于以下示例：

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

要使用 MongoCredential 类指定 X.509 认证机制，请使用 createMongoX509Credential() 方法。同时，通过调用 applyToSslSettings() 方法并设置 SslSettings.Builder 块中的 enabled 属性为 true 来启用 TLS。创建 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 数据源

下一步

企业身份验证