企业身份验证机制
Overview
在本指南中,您可以了解如何使用 MongoDB Enterprise Edition 独有的每种身份验证机制对 MongoDB 进行身份验证。
您可以在最新版本的 MongoDB Enterprise Edition 中使用以下机制:
要使用其他机制进行身份验证,请参阅身份验证机制指南。 有关建立与MongoDB 集群连接的更多信息,请阅读我们的连接指南。
指定身份验证机制
您可以使用以下任一方式在连接到 MongoDB 时指定身份验证机制和凭据:
连接字符串
一个
MongoCredential
工厂方法
连接字符串(也称为连接 uri)指定如何连接到 MongoDB 集群并对其进行身份验证。
要使用连接字符串进行身份验证,请将您的设置包含在连接字符串中并将其传递给MongoClients.create()
方法以实例化您的MongoClient
。选择 Connection String选项卡以查看使用连接字符串进行身份验证的事务语法。
或者,您可以使用 MongoCredential
类指定身份验证详细信息。MongoCredential
类包含静态工厂方法,可构造包含身份验证机制和档案的实例。使用 MongoCredential
辅助类时,您需要在构造 MongoClient
时使用 MongoClientSettings.Builder
类来配置连接设置。选择 MongoCredential 标签页,查看使用 MongoCredential
进行身份验证的事务语法。
有关这些类和方法的更多信息,请参阅以下 API 文档:
机制
Kerberos (GSSAPI)
通用安全服务 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_KEY或JAVA_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));
LDAP (Plain)
在 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
重要
MONGODB-OIDC 身份验证机制要求在 Linux 平台上运行 MongoDB Server v 7.0或更高版本。
以下部分介绍如何使用 MONGODB-OIDC 身份验证机制对各种平台进行身份验证。
有关 MONGODB-OIDC 身份验证机制的更多信息,请参阅 MongoDB Server 手册中的OpenID Connect 身份验证和MongoDB Server 参数。
Azure IMDS
如果应用程序在 Azure VM 上运行,或以其他方式使用 Azure 实例元数据服务 (IMDS),您可以使用 Java 驱动程序的内置 Azure 支持对 MongoDB 进行身份验证。
您可以使用Azure MongoCredential
或作为连接 的一部分来指定 IMDS OIDC身份验证。string
从Connection String或MongoCredential标签页中进行选择,以查看相应的语法。
将以下代码中的<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());
GCP IMDS
如果您的应用程序在 Google Compute Engine 虚拟机上运行,或以其他方式使用 GCP实例元数据服务 ,您可以使用Java驱动程序的内置GCP支持对MongoDB进行身份验证。
您可以使用GCP MongoCredential
或作为连接 的一部分来指定 IMDS OIDC身份验证。string
从Connection String或MongoCredential标签页中进行选择,以查看相应的语法。
将以下代码中的<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
作为参数并返回 OidcCallbackResult
的 OidcCallback
函数式接口的其他实现。
以下示例使用示例回调从本地文件系统中名为"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());