Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB 驱动程序 → java sync

身份验证机制

在此页面上

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

概述

在本指南中，您可以了解如何使用 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 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

有关 MongoDB 支持的质询-响应 (CR) 和加盐质询-响应身份验证机制 (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 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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 会话令牌的价值

适用于 Java 的 AWS SDK

版本 v4.8 新增。

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

要使用 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);
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);
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 容器档案进行身份验证，请确保没有设置上述环境变量。驱动程序会从默认 IPv4 EC2 实例元数据端点获取档案。

在 MongoCredential 中指定您的档案

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

您只能为MongoCredential.createAwsCredential()方法提供编程访问密钥。如果您需要提供 ECS 或 EC 2容器档案，请按照在环境中指定档案或适用于 Java 的 AWS 开发工具包中的说明进行操作。

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

  1. 指定身份验证机制

  2. 提供档案

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

MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
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>");
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 here to fetch new credentials here
    // Return the new credentials
    return new AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>");
};
MongoCredential credential = MongoCredential.createAwsCredential(null, null)
        .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier);
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 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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

← 使用 JNDI 数据源连接到 MongoDB
企业身份验证机制 →

在此页面上