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

企业身份验证机制

在此页面上

  • Overview
  • 指定身份验证机制
  • 机制
  • Kerberos (GSSAPI)
  • LDAP (Plain)
  • MONGODB-OIDC

在本指南中,您可以了解如何使用 MongoDB Enterprise Edition 独有的每种身份验证机制对 MongoDB 进行身份验证。

您可以在最新版本的 MongoDB Enterprise Edition 中使用以下机制:

  • Kerberos (GSSAPI)

  • LDAP (Plain)

  • MONGODB-OIDC

要使用其他机制进行身份验证,请参阅身份验证机制指南。 有关建立与MongoDB 集群连接的更多信息,请阅读我们的连接指南。

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

  • 连接字符串

  • 一个 MongoCredential工厂方法

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

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

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

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

通用安全服务 API ( GSSAPI ) 身份验证机制允许用户使用用户的主体名称对 Kerberos 服务进行身份验证。

注意

该方法引用GSSAPI 身份验证机制而不是Kerberos ,因为驱动程序使用 GSSAPI RFC-4652 SASL 机制。

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

  • username:URL 编码的主体名称,例如 "username%40REALM.ME"

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

  • port:MongoDB 部署的端口号

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

要使用连接字符串指定 GSSAPI 身份验证机制:

  • authMechanism URL 参数分配给值GSSAPI

  • 可选)将authSource URL 参数分配给值$external

注意

如果指定GSSAPI 机制,则不能将authSource 分配给$external 以外的任何值。

用于实例化 MongoClient 的代码如下所示:

MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI");

要使用MongoCredential类指定 GSSAPI 身份验证机制,请使用createGSSAPICredential()方法。 用于实例化MongoClient的代码如下所示:

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

要获取 Kerberos 票证 ,GSSAPI Java 库要求您指定 Realm 和密钥分发中心 (KDC) 系统属性。请参阅以下示例中的示例设置:

java.security.krb5.realm=MYREALM.ME
java.security.krb5.kdc=mykdc.myrealm.me

您可能需要指定以下一个或多个附加MongoCredential机制属性,具体取决于您的 Kerberos 设置:

  • SERVICE_NAME

  • CANONICALIZE_HOST_NAME

  • JAVA_SUBJECT

  • JAVA_SASL_CLIENT_PROPERTIES

  • JAVA_SUBJECT_PROVIDER

重要

您只能使用MongoCredential指定以下 GSSAPI 属性:

  • JAVA_SUBJECT

  • JAVA_SASL_CLIENT_PROPERTIES

  • JAVA_SUBJECT_PROVIDER

选择MongoCredential标签页,查看如何指定它们。

要指定某一 GSSAPI 附加属性,请将其作为 URL 参数包含在连接字符串中,格式如下: <PROPERTY_NAME>:<value>

使用 GSSAPI 和其他属性实例化MongoClient的代码可能如下所示:

MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService");

要指定某一 GSSAPI 附加属性,请在MongoCredential实例上调用withMechanismProperty()方法,并将属性名称和值作为参数传递。 使用MongoCredential类中定义的属性名称常量:

选择SERVICE_NAME_KEYJAVA_SUBJECT_KEY标签页,查看示例代码,以实例化使用 GSSAPI 和所选属性的MongoCredential

MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService");
LoginContext loginContext = new LoginContext(<LoginModule implementation from JAAS config>);
loginContext.login();
Subject subject = loginContext.getSubject();
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);

默认情况下,Java 驱动程序按MongoClient实例缓存 Kerberos 票证。 如果您的部署需要频繁创建和销毁MongoClient实例,则可以将默认 Kerberos 票证缓存行为更改为按进程缓存,以提高性能。

要按进程缓存 Kerberos 票证,必须使用MongoCredential身份验证机制,因为连接字符串身份验证机制不支持JAVA_SUBJECT_PROVIDER机制属性。如果您想按进程缓存 Kerberos 票证,请选择MongoCredential标签页以了解如何完成此操作。

要按进程缓存 Kerberos 票证,必须指定JAVA_SUBJECT_PROVIDER 机制属性并提供 KerberosSubjectProvider 在您的MongoCredential 实例中。将 Java 驱动程序配置为按进程缓存 Kerberos 票证的代码如下所示:

/* all MongoClient instances sharing this instance of KerberosSubjectProvider
will share a Kerberos ticket cache */
String myLoginContext = "myContext";
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
/* login context defaults to "com.sun.security.jgss.krb5.initiate"
if unspecified in KerberosSubjectProvider */
credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
new KerberosSubjectProvider(myLoginContext));

注意

在 Windows 上,Oracle 的 JRE 使用 LSA 而不是 SSPI 在实施 GSSAPI 时,限制了与 Windows Active Directory 的互操作性和单点登录的实施。有关详细信息,请参阅以下文章:

在 MongoDB Enterprise 版 3.4 及更高版本中可用。

您可以使用目录服务器用户名和密码向轻量级目录访问协议 (LDAP) 服务器进行身份验证。

提示

身份验证机制名为PLAIN 而不是LDAP ,因为它使用 RFC- 中定义的 PLAIN 简单身份验证和安全层 (SASL)4616 进行身份验证。 。

您可以通过将 authMechanism 参数设置为 PLAIN 并将LDAP用户名和密码包含在连接string中来指定此身份验证机制。

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

  • username:您的 LDAP 用户名

  • password:LDAP 用户的密码

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

  • port:MongoDB 部署的端口号

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

使用连接字符串指定 LDAP (PLAIN) 身份验证机制的具体操作如下:

  • authMechanism URL 参数分配给值PLAIN

  • 可选)将authSource URL 参数分配给值$external

注意

如果指定PLAIN 机制,则不能将authSource 分配给$external 以外的任何值。

用于实例化 MongoClient 的代码如下所示:

MongoClient mongoClient = MongoClients.create("<db_username>:<db_password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN");

要使用MongoCredential类指定 LDAP (PLAIN) 身份验证机制,请使用createPlainCredential()方法。 用于实例化MongoClient的代码如下所示:

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

重要

MONGODB-OIDC 身份验证机制要求在 Linux 平台上运行 MongoDB Server v 7.0或更高版本。

以下部分介绍如何使用 MONGODB-OIDC 身份验证机制对各种平台进行身份验证。

有关 MONGODB-OIDC 身份验证机制的更多信息,请参阅 MongoDB Server 手册中的OpenID Connect 身份验证MongoDB Server 参数

如果应用程序在 Azure VM 上运行,或以其他方式使用 Azure 实例元数据服务 (IMDS),您可以使用 Java 驱动程序的内置 Azure 支持对 MongoDB 进行身份验证。

您可以使用Azure MongoCredential或作为连接 的一部分来指定 IMDS OIDC身份验证。string

Connection StringMongoCredential标签页中进行选择,以查看相应的语法。

将以下代码中的<percent-encoded audience>占位符替换为MongoDB 部署上配置的受众服务器参数的百分比编码值。

逗号 ( , ) 字符及其编码 ( %2C ) 被保留,在值中使用这些字符会导致驾驶员将逗号解释为键值对的分隔符。 您必须在MongoCredential实例中指定包含逗号的值,如MongoCredential标签页中所示。

MongoClient mongoClient = MongoClients.create(
"mongodb://<db_username>@<hostname>:<port>/?" +
"?authMechanism=MONGODB-OIDC" +
"&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");

<db_username>占位符替换为Azure托管身份或企业应用程序的客户端ID或应用程序 ID 。 将<audience>占位符替换为MongoDB 部署上配置的audience服务器参数的值。

MongoCredential credential = MongoCredential.createOidcCredential("<db_username>")
.withMechanismProperty("ENVIRONMENT", "azure")
.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
.credential(credential)
.build());

如果您的应用程序在 Google Compute Engine 虚拟机上运行,或以其他方式使用 GCP实例元数据服务 ,您可以使用Java驱动程序的内置GCP支持对MongoDB进行身份验证。

您可以使用GCP MongoCredential或作为连接 的一部分来指定 IMDS OIDC身份验证。string

Connection StringMongoCredential标签页中进行选择,以查看相应的语法。

将以下代码中的<percent-encoded audience>占位符替换为MongoDB 部署上配置的受众服务器参数的百分比编码值。

逗号 ( , ) 字符及其编码 ( %2C ) 被保留,在值中使用这些字符会导致驾驶员将逗号解释为键值对的分隔符。 您必须在MongoCredential实例中指定包含逗号的值,如MongoCredential标签页中所示。

MongoClient mongoClient = MongoClients.create(
"mongodb://<hostname>:<port>/?" +
"authMechanism=MONGODB-OIDC" +
"&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>");

<audience>占位符替换为MongoDB 部署上配置的audience服务器参数的值。

MongoCredential credential = MongoCredential.createOidcCredential()
.withMechanismProperty("ENVIRONMENT", "gcp")
.withMechanismProperty("TOKEN_RESOURCE", "<audience>");
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
.credential(credential)
.build());

Java 驱动程序并不为所有平台提供内置支持,包括 Azure Functions 和 Azure Kubernetes Service (AKS)。 相反,您必须定义自定义回调,才能使用 OIDC 从这些平台进行身份验证。 为此,请使用"OIDC_CALLBACK"身份验证属性,如以下代码示例所示:

MongoCredential credential = MongoCredential.createOidcCredential(null)
.withMechanismProperty("OIDC_CALLBACK", (context) -> {
String accessToken = ...
return new OidcCallbackResult(accessToken);
});

"OIDC_CALLBACK" 属性的值必须是Lambda或接受 OidcCallbackContext 作为参数并返回 OidcCallbackResultOidcCallback 函数式接口的其他实现。

以下示例使用示例回调从本地文件系统中名为"access-token.dat"的文件中检索 OIDC 令牌:

MongoCredential credential = MongoCredential.createOidcCredential(null)
.withMechanismProperty("OIDC_CALLBACK", (context) -> {
string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
return new OidcCallbackResult(accessToken);
});
MongoClient mongoClient = MongoClients.create(
MongoClientSettings.builder()
.applyToClusterSettings(builder ->
builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
.credential(credential)
.build());

后退

身份验证机制