身份验证机制

在此页面上

Overview

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

Overview

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

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

默认
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
x.509

要使用 Kerberos或LDAP进行身份验证，请参阅《企业身份验证机制》指南。

有关与 MongoDB 集群建立连接的更多信息，请参阅我们的连接指南。

指定身份验证机制

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

连接字符串
MongoCredential工厂方法

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

要使用连接字符串进行身份验证，请将您的设置包含在连接字符串中，并将其传递给MongoClient.create()方法以实例化MongoClient 。每个部分的 Connection String标签页提供了使用连接字符串进行身份验证的语法。

或者，您可以使用MongoCredential类指定身份验证详细信息。 MongoCredential类包含静态工厂方法，用于构造包含身份验证机制和档案的实例。使用MongoCredential助手类时，您需要在构造MongoClient时使用MongoClientSettings.Builder类来配置连接设置。每个部分中的MongoCredential标签页提供了使用MongoCredential进行身份验证的语法。

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

机制

默认

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

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR

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

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

db_username - 您的MongoDB 数据库用户名
db_password - 您的MongoDB 数据库用户的密码
hostname - 可供客户端访问的 MongoDB 服务器的网络地址
port - MongoDB Server 的端口号
authenticationDb — 包含用户的身份验证数据的 MongoDB 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

要使用连接字符串指定默认身份验证机制，请忽略该机制。用于实例化MongoClient的代码应类似于以下内容：

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

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

val credential = MongoCredential.createCredential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

有关支持的质询-响应 (CR) 和加盐质询-响应身份验证机制 (SCRAM )MongoDB 的更多信息，请参阅SCRAM MongoDB Server手册的部分。

`SCRAM-SHA-256`

注意

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

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

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

db_username - 您的MongoDB 数据库用户名。
db_password - 您的MongoDB 数据库用户的密码。
hostname — 可供客户端访问的 MongoDB Server 的网络地址。
port — MongoDB Server的端口号。
authenticationDb — 包含用户的身份验证数据的 MongoDB 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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

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

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

val credential = MongoCredential.createScramSha256Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

`SCRAM-SHA-1`

注意

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

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

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

db_username - 您的MongoDB 数据库用户名。
db_password - 您的MongoDB 数据库用户的密码。
hostname — 可供客户端访问的 MongoDB Server 的网络地址。
port — MongoDB Server的端口号。
authenticationDb — 包含用户的身份验证数据的 MongoDB 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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

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

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

val credential = MongoCredential.createScramSha1Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", "<port>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

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

Amazon Web Services SDK

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

获取档案的多种选项
档案缓存可帮助应用程序避免速率限制
与 Elastic Kubernetes Service 一起使用的凭证提供者管理。

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

指定身份验证机制
将该 SDK 作为依赖项添加到项目中
使用档案提供程序链中的一种方法提供档案

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

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

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

val mongoClient =
    MongoClient.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 文档，了解您需要的版本：

要进一步了解驱动程序用于获取凭证的 AWS SDK for Java v2 类，请参阅 DefaultCredentialsProvider API 文档。
从使用默认凭证提供者链部分了解如何向该课程提供凭证。
如需进一步了解驱动程序用于获取凭证的 AWS SDK for Java v1 类，请参阅 DefaultAWSCredentialsProviderChain API 文档。
从使用默认凭证提供者链部分了解如何向该课程提供凭证。

注意

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

在环境中指定您的档案

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

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

指定身份验证机制
添加适当的环境变量

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

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

val credential = MongoCredential.createAwsCredential(null, null)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder: ClusterSettings.Builder ->
        builder.hosts(
            listOf(ServerAddress("<atlasUri>"))
        )
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

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

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

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

编程访问密钥
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的行。

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

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<your ECS endpoint>

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

在 MongoCredential 中指定您的档案

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

您只能向MongoCredential.createAwsCredential()方法提供编程访问权限密钥。如果您需要提供 ECS 或 EC2 容器凭证，请按照在环境或Amazon Web Services SDK 中指定档案中的说明进行操作。

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

指定身份验证机制
提供档案

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

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

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

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<atlasUri>"))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

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

val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier {
    // Add your code here to fetch new credentials
    // Return the new credentials
    AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>")
}
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
    .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier)
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(ServerAddress("<hostname>", "<port>")))
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

如果您必须在连接中提供 IAMAmazon Web Servicesstring 档案，您可以通过调用MongoClientSettings applyConnectionString() 将其添加到您的中。方法：

val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>")
val settings = MongoClientSettings.builder()
    .applyConnectionString(connectionString)
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

`X.509`

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

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

hostname — 可供客户端访问的 MongoDB Server 的网络地址。
port — MongoDB Server的端口号。
authenticationDb — 包含用户的身份验证数据的 MongoDB 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

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

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

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

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

val credential = MongoCredential.createMongoX509Credential()
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(
            ServerAddress("<hostname>", "<port>"))
        )
    }
    .applyToSslSettings { builder ->
        builder.enabled(true)
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

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

后退

使用 SOCKS5 代理连接到 MongoDB

来年

企业身份验证机制