企业身份验证机制

本页内容

概述

指定身份验证机制
机制
kerberos (GSSAPI)
LDAP (PLAIN)
MONGODB-OIDC

概述

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

您可以使用以下机制与最新版本的MongoDB Enterprise Edition进行连接：

kerberos (GSSAPI)
LDAP (PLAIN)
MONGODB-OIDC

身份验证机制指南.

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

指定身份验证机制

您可以通过以下方式指定身份验证机制和凭据来连接到MongoDB：

连接字符串
AMongoCredential工厂方法

连接字符串（也称为连接URI）指定如何连接和验证到您的MongoDB集群。

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

或者，您可以使用MongoCredential类来指定您的身份验证详细信息。该MongoCredential类包含静态工厂方法，用于构建包含您的身份验证机制和凭据的实例。当您使用MongoCredential辅助类时，您需要使用MongoClientSettings.Builder类来配置您的连接设置，在构建您的MongoClient时。每个部分的MongoCredential选项卡提供了使用MongoCredential进行身份验证的语法。

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

机制

Kerberos (GSSAPI)

通用安全服务API（GSSAPI）认证机制允许用户使用用户的主名称来认证到Kerberos服务。

注意

此方法指的是GSSAPI认证机制而不是Kerberos，因为驱动程序使用GSSAPI RFC-4652 SASL机制。

以下代码片段显示了如何指定认证机制，使用以下占位符

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

选择下面的连接字符串或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库需要您指定领域和密钥分发中心（KDC）系统属性。请参阅以下示例中的示例设置

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

根据您的Kerberos配置，您可能需要指定以下一个或多个额外的MongoCredential机制属性

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参数，格式为：<属性名>:<值>。

使用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 票据，您必须在您的 MongoCredential 实例中指定 JAVA_SUBJECT_PROVIDER 机制属性并提供一个 KerberosSubjectProvider。配置 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活动目录和单点登录实现的互操作性。有关更多信息，请参阅以下文章

LDAP (PLAIN)

在MongoDB企业版3.4及以后版本中可用。

您可以使用目录服务器的用户名和密码来验证 Lightweight Directory Access Protocol (LDAP) 服务器。

提示

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

您可以通过将 authMechanism 参数设置为 PLAIN 并在连接字符串中包含您的 LDAP 用户名和密码来指定此认证机制。

以下代码片段显示了如何指定认证机制，使用以下占位符

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

选择下面的连接字符串或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 认证机制要求 MongoDB 服务器 v7.0 或更高版本，在 Linux 平台上运行。

以下部分描述了如何使用 MONGODB-OIDC 认证机制来认证到不同的平台。

有关MONGODB-OIDC认证机制的更多信息，请参阅MongoDB服务器手册中的OpenID Connect认证和MongoDB服务器参数。

Azure IMDS

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

您可以通过使用MongoCredential实例或在连接字符串中指定您的凭据来指定Azure IMDS OIDC认证。

选择“连接字符串”或“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部署上配置的服务器参数的值。

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())

Google云平台实例元数据服务（GCP IMDS）

如果你的应用程序运行在Google Compute Engine虚拟机（VM）上，或者使用Google云平台实例元数据服务（GCP Instance Metadata Service），你可以通过使用Kotlin驱动程序的内置GCP支持来使用MongoDB进行认证。

您可以通过使用一个MongoCredential实例或者通过在连接字符串中指定您的凭据来指定GCP IMDS OIDC认证。

选择“连接字符串”或“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或其他实现了OidcCallback函数接口的实现，该接口接受一个OidcCallbackContext作为参数，并返回一个OidcCallbackResult。

以下示例使用一个示例回调来从本地文件系统中名为"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()
)

身份验证

稳定API