企业身份验证机制

在此页面上

Overview

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

Overview

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

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

Kerberos (GSSAPI)
LDAP (Plain)
MONGODB-OIDC

身份验证机制指南。

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

指定身份验证机制

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

连接字符串
一个 MongoCredential工厂方法

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

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

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

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

机制

Kerberos (GSSAPI)

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

注意

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

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

Kerberos principal - URL 编码的主体名称，例如 "username%40REALM.ME"
hostname - 可供客户端访问的 MongoDB 服务器的网络地址
port - MongoDB Server 的端口号

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

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

将authMechanism URL 参数分配给值GSSAPI
（可选）将authSource URL 参数分配给值$external

注意

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

用于实例化MongoClient的代码应类似于以下内容：

val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI")
val mongoClient = MongoClient.create(connectionString)

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

val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

要获取 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的代码可能如下所示：

val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService")
val mongoClient = MongoClient.create(connectionString)

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

选择SERVICE_NAME_KEY或JAVA_SUBJECT_KEY标签页，查看示例代码，以实例化使用 GSSAPI 和所选属性的MongoCredential ：

val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService")

val loginContext = LoginContext("<LoginModule implementation from JAAS config>")
loginContext.login()
val subject: Subject = loginContext.subject
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject)

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

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

要按进程缓存Kerberos票证，必须指定JAVA_SUBJECT_PROVIDER 机制属性并提供 KerberosSubjectProvider 在您的MongoCredential 实例中。将Kotlin驾驶员配置为按进程缓存Kerberos票证的代码应类似于以下内容：

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

注意

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

LDAP (Plain)

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

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

提示

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

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

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

LDAP username - 您的 LDAP 用户名
password - LDAP 用户的密码
hostname - 可供客户端访问的 MongoDB 服务器的网络地址
port - MongoDB Server 的端口号

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

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

将authMechanism URL 参数分配给值PLAIN
（可选）将authSource URL 参数分配给值$external

注意

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

用于实例化MongoClient的代码应类似于以下内容：

val connectionString = ConnectionString("<LDAP username>:<password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN")
val mongoClient = MongoClient.create(connectionString)

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

val credential = MongoCredential.createPlainCredential("<LDAP username>", "$external", "<password>".toCharArray())
val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder ->
        builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
    }
    .credential(credential)
    .build()
val mongoClient = MongoClient.create(settings)

MONGODB-OIDC

重要

MONGODB-OIDC身份验证机制需要在Linux平台上运行的MongoDB 服务器 v 7.0或更高版本。

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

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

Azure IMDS

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

您可以通过使用实例或在连接中指定您的凭证来指定 AzureIMDS OIDC身份验证。MongoCredentialstring

从Connection String或MongoCredential标签页中进行选择，以查看相应的语法。

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

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

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

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

val credential = MongoCredential.createOidcCredential("<OIDC principal>")
    .withMechanismProperty("ENVIRONMENT", "azure")
    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
val mongoClient = MongoClient.create(
        MongoClientSettings.builder()
            .applyToClusterSettings { builder ->
                builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
            }
        .credential(credential)
        .build())

GCP IMDS

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

您可以通过使用GCP MongoCredential实例或在连接中指定您的档案来指定 IMDS OIDC凭证身份验证。string

从Connection String或MongoCredential标签页中进行选择，以查看相应的语法。

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

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

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

val credential = MongoCredential.createOidcCredential("<OIDC principal>")
    .withMechanismProperty("ENVIRONMENT", "gcp")
    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build())

自定义回调

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

val credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
        val accessToken = "..."
        OidcCallbackResult(accessToken)
    }

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

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

val credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
        val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
        OidcCallbackResult(accessToken)
    }
val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build()
)

后退

身份验证机制

来年

Stable API