文档菜单
文档首页
/ / /
Node.js 驱动
/ /

企业身份验证机制

本页面

  • Kerberos (GSSAPI/SSPI)
  • LDAP (PLAIN)
  • MONGODB-OIDC
  • API 文档

在本指南中,您可以找到使用 MongoDB 企业版中可用的每种身份验证机制连接到 MongoDB 的示例代码Kerberos (GSSAPI/SSPI)LDAP (PLAIN),和 MONGODB-OIDC

注意

Node.js 驱动在 UNIX 上使用 MIT Kerberos 库支持 Kerberos,在 Windows 上使用 SSPI API 支持。

《GSSAPI》身份验证机制使用您的用户主体对Kerberos服务进行认证。

您可以通过在您的连接字符串指定选项时执行以下操作来指定此身份验证机制:连接字符串:

  • authMechanism参数设置为GSSAPI

  • 如果使用除mongodb以外的值,请在authMechanismProperties参数中设置SERVICE_NAME值。

  • 如果需要自定义服务域,请在authMechanismProperties参数中指定一个SERVICE_REALM值。

  • 如果需要主机名的规范表示,请在authMechanismProperties参数中指定一个CANONICALIZE_HOST_NAME值。此属性可以取以下值:

    • none:(默认值)不执行主机名规范表示

    • forward:执行正向DNS查找以规范表示主机名

    • forwardAndReverse:执行正向DNS查找,然后对该值执行反向查找以规范表示主机名

重要

参数gssapiServiceName已弃用,可能在驱动程序的将来版本中删除。请在连接URI中使用authMechanismProperties=SERVICE_NAME:<您的服务名称>代替。有关更多信息,请参阅authMechanismProperties参数文档。

以下代码示例使用《GSSAPI》对UNIX的Kerberos进行认证。

重要

始终使用encodeURIComponent方法对主体进行URI编码,以确保它被正确解析。

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const principal = encodeURIComponent("<Kerberos principal and realm>");
const serviceRealm = "<Kerberos service realm>";
const canonicalizationSetting = "<canonicalization setting>";
const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`;
const authMechanism = "GSSAPI";
// Connection URI
const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`;
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
try {
// Establish and verify connection
await client.db("admin").command({ ping: 1 });
console.log("Connected successfully to server");
} finally {
// Ensures that the client will close when you finish/error
await client.close();
}
}
run().catch(console.dir);

注意

此方法指的是《GSSAPI》身份验证机制而不是《Kerberos》,因为驱动程序通过GSSAPI RFC-4652,SASL机制。

PLAIN 认证机制使用您的用户名和密码来认证 Lightweight Directory Access Protocol (LDAP) 服务器。

您可以通过将 authMechanism 参数设置为 PLAIN 并在以下示例代码中包括您的 LDAP 用户名和密码来指定此认证机制。

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const ldapUsername = "<LDAP username>";
const ldapPassword = "<LDAP password>";
const authMechanism = "PLAIN";
// Connection URI
const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`;
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
try {
// Establish and verify connection
await client.db("admin").command({ ping: 1 });
console.log("Connected successfully to server");
} finally {
// Ensures that the client will close when you finish/error
await client.close();
}
}
run().catch(console.dir);

注意

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

重要

MONGODB-OIDC 认证机制需要 Linux 平台上运行的 MongoDB Server v7.0 或更高版本。

以下各节描述了如何使用 MONGODB-OIDC 认证机制从各种平台进行认证。

有关 MONGODB-OIDC 认证机制的信息,请参阅 MongoDB Server 手册中的 OpenID Connect 认证MongoDB 服务器参数

如果您的应用程序运行在Azure虚拟机上,或者使用了Azure实例元数据服务(IMDS),您可以使用Node.js驱动程序的内置Azure支持通过认证到MongoDB。

要指定Azure IMDS OIDC作为认证机制,请将以下选项设置在您的连接字符串中

  • username:如果您使用的是Azure托管身份,请将其设置为托管身份的客户端ID。如果您使用服务主体代表企业应用程序,请将其设置为服务主体的应用程序ID。否则,省略此选项。

  • authMechanism:设置为MONGODB-OIDC

  • authMechanismProperties:设置为ENVIRONMENT:azure,TOKEN_RESOURCE:<audience>。将<audience>占位符替换为您在MongoDB部署上配置的audience参数的值。

以下代码示例展示了如何设置前面的连接选项

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<username>@<hostname>:<port>/?authMechanism=MONGODB-OIDC"
+ "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

如果你的应用程序运行在Google Compute Engine虚拟机上,或者使用Google Cloud平台实例元数据服务,你可以通过Node.js驱动程序内置的GCP支持来通过MongoDB进行身份验证。

要指定GCP IMDS OIDC作为身份验证机制,请将以下选项设置在连接字符串中

  • authMechanism:设置为MONGODB-OIDC

  • authMechanismProperties:设置为ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>。将<audience>占位符替换为MongoDB部署上配置的audience参数的值。

以下代码示例展示了如何设置前面的连接选项

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC"
+ "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

Node.js驱动程序并不提供对包括Azure Functions和Azure Kubernetes Service (AKS)在内的所有平台的内置支持。相反,你必须定义一个自定义回调来使用OIDC从这些平台进行身份验证。

首先,定义一个函数来检索用于OIDC身份验证的访问令牌。此函数必须具有以下签名

const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => { }

OIDCCallbackParams参数包含以下属性,您可以在函数内部访问这些属性

属性
timeoutContext
一个AbortSignal,在30秒后终止身份验证工作流程
version
当前的OIDC API版本
idpInfo
服务器返回的身份提供者信息
username
如果有的话,连接字符串中包含的用户名
refreshToken
如果有的话,用于从发行者请求新的访问令牌的刷新令牌

回调函数必须返回一个OIDCResponse对象。该对象包含以下属性

属性
accessToken
用于身份验证的访问令牌。
expiresInSeconds
可选。 访问令牌到期前的秒数。
refreshToken
可选。 用于从发行商请求新的访问令牌的刷新令牌。

以下示例展示了从本地文件系统中名为 access-token.dat 的文件中检索 OIDC 访问令牌的回调函数。

const fs = require("node:fs");
const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => {
const token = fs.readFileSync("access-token.dat", "utf8");
return {
accessToken: token,
expiresInSeconds: 300,
refreshToken: token
};
}

定义您的回调函数后,将其作为 authMechanismProperties 参数的一部分传递给 MongoClient 构造函数。Node.js 驱动程序支持以下认证模式

  • 机器认证: 适用于无需人工交互的 Web 服务和其他应用程序。选择机器回调 选项卡以查看此语法的示例。

  • 人工认证: 适用于数据库工具、命令行实用程序和其他涉及直接人工交互的应用程序。选择 人工回调 选项卡以查看此语法的示例。

对于机器认证,将回调函数分配给 authMechanismProperties.OIDC_CALLBACK 属性,如下例所示

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
authMechanismProperties: {
OIDC_CALLBACK: myCallback
}
});

对于人工认证,将回调函数分配给 authMechanismProperties.OIDC_HUMAN_CALLBACK 属性,如下例所示

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
authMechanismProperties: {
OIDC_HUMAN_CALLBACK: myCallback
}
});

有关本指南中讨论的方法和类型的更多信息,请参阅以下 API 文档

返回

身份验证