企业身份验证机制
在本指南中,您可以找到使用 MongoDB 企业版中可用的每种身份验证机制连接到 MongoDB 的示例代码Kerberos (GSSAPI/SSPI)
,LDAP (PLAIN)
,和 MONGODB-OIDC
。
Kerberos (GSSAPI/SSPI)
注意
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机制。
LDAP (PLAIN)
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
重要
MONGODB-OIDC 认证机制需要 Linux 平台上运行的 MongoDB Server v7.0 或更高版本。
以下各节描述了如何使用 MONGODB-OIDC 认证机制从各种平台进行认证。
有关 MONGODB-OIDC 认证机制的信息,请参阅 MongoDB Server 手册中的 OpenID Connect 认证 和 MongoDB 服务器参数。
Azure IMDS
如果您的应用程序运行在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);
GCP IMDS
如果你的应用程序运行在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 文档
有关本指南中讨论的方法和类型的更多信息,请参阅以下 API 文档