身份验证机制

在此页面上

Overview

指定身份验证机制
机制
默认
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-AWS
x.509
API 文档

此版本的文档已存档，不再提供支持。查看最新文档，学习；了解如何升级您的.NET/ C#驱动程序版本。

Overview

在本指南中，您可以了解如何使用 MongoDB Community Edition 提供的身份验证机制对 MongoDB 进行身份验证。身份验证机制是驱动程序和服务器在连接之前确认客户端身份以确保安全的过程。

您可以在最新版本的 MongoDB Community Edition 中使用以下身份验证机制：

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-AWS
x.509

要使用 GSSAPI/Kerberos或LDAP进行身份验证，请参阅企业身份验证机制基础知识页面。有关与MongoDB 集群建立连接的更多信息，请参阅连接指南。

指定身份验证机制

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

连接字符串，也称为连接 URI，它是一个指示驱动程序如何连接到 MongoDB 部署以及连接时如何表现的字符串。
支持的身份验证机制的工厂方法，包含在 MongoCredential 类中。

机制

以下示例包含使用以下占位符的代码示例：

<db_username> - MongoDB 用户名。
<db_password> — MongoDB 用户的密码。
<hostname> - MongoDB server 的网络地址，可由您的客户端访问。
<port> — MongoDB 服务器的端口号。
<authenticationDb> — 包含用户的身份验证数据的 MongoDB 数据库。如果省略此参数，驱动程序则会使用默认值 admin。

默认

默认身份验证机制设置使用以下身份验证机制之一，具体取决于服务器支持的 MongoDB 版本：

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR

注意

MongoDB 4.0 版本使用 SCRAM 作为默认机制，不再支持 MONGODB-CR。

选择 Connection String 或 MongoCredential 标签页，查看用于指定默认身份验证机制的相应事务语法：

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>");

var credential = MongoCredential.CreateCredential("<authenticationDb>", "<db_username>", "<db_password>");
var settings = MongoClientSettings.FromConnectionString("<connection string>");
settings.Credential = credential;
var mongoClient = new MongoClient(settings);

SCRAM-SHA-256

SCRAM-SHA-256 是一种挑战-响应身份验证机制 (SCRAM)，使用通过 SHA-256 算法加密的用户名和密码来验证用户身份。

您可以在连接字符串中指定 SCRAM-SHA-256 身份验证机制，如下所示：

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-256");

提示

默认机制

如果 MongoDB 服务器版本支持，MongoDB 4.0 及更高版本会使用 SCRAM-SHA-256 作为默认身份验证机制。

要了解有关指定默认机制的更多信息，请参阅默认值。

SCRAM-SHA-1

SCRAM-SHA-1 是一种 Salted 挑战 — 响应机制 (SCRAM)，使用 SHA-1 算法加密的用户名和密码来验证用户身份。

您可以在连接字符串中指定 SCRAM-SHA-1 身份验证机制，如下所示：

var mongoClient = new MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-1");

提示

默认机制

如果服务器不支持 SCRAM-SHA-256，MongoDB 4.0 版本会使用 SCRAM-SHA-1 作为默认身份验证机制。

要了解有关指定默认机制的更多信息，请参阅默认值。

MONGODB-AWS

注意

MONGODB-AWS身份验证机制仅适用于 MongoDB Atlas 上的 MongoDB 部署。

MONGODB-AWS 身份验证机制使用 Amazon Web Services Identity and Access Management (AWS IAM) 凭证对用户进行身份验证。您可以显示指定您的凭证，也可以指示驱动程序从外部源自动检索凭证。

以下部分包含使用以下占位符的代码示例：

<awsKeyId> — AWS 访问密钥 ID 的值
<awsSecretKey> - AWS 秘密访问密钥的值
<awsSessionToken> - AWS 会话令牌的值

提示

要了解有关使用 AWS IAM 配置 MongoDB Atlas 的更多信息，请参阅使用 AWS IAM 角色设置无密码身份验证指南。

指定 AWS IAM 凭证

您可以使用 MongoCredential 对象或作为连接字符串的一部分，在 MongoClientSettings 对象中提供 AWS IAM 档案。选择 Connection String 或 MongoCredential 选项卡，查看指定档案的相应语法：

var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>[:<port>]?authSource=$external&authMechanism=MONGODB-AWS";
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

如果您使用的是 AWS 会话令牌，则请在连接字符串中包含 authMechanismProperties 参数，如下所示：

var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>[:<port>]?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>";

var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb+srv://<hostname>[:<port>]");
mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalIdentity("<awsKeyId>"), new PasswordEvidence("<awsSecretKey>"));
var client = new MongoClient(mongoClientSettings);

如果您使用的是Amazon Web Services会话令牌，请对 MongoCredential 对象调用 WithMechanismProperty() 方法，如下所示：

mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalIdentity("<awsKeyId>"), new PasswordEvidence("<awsSecretKey>"))
    .WithMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>");

自动检索档案

您可以指示 .NET/C# 驱动程序使用 AWS 开发工具包从外部源自动检索您的档案，而无需在 MongoClientSettings 中指定您的 AWS IAM 档案。要指示驱动程序检索档案，请执行以下动作：

指定 MONGODB-AWS 作为身份验证机制
指定身份验证源位于 MongoDB 外部
在适当的位置设置档案

您可以使用MongoCredential对象或作为连接字符串的一部分来指定身份验证机制和来源。选择Connection String或MongoCredential标签页可查看用于指定MONGODB-AWS身份验证机制和外部身份验证源的相应事务语法：

var connectionString = "mongodb+srv://<hostname>[:<port>]?authMechanism=MONGODB-AWS&authSource=$external";
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb+srv://<hostname>[:<port>]");
mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalAwsIdentity(), new ExternalEvidence());
var client = new MongoClient(mongoClientSettings);

指定身份验证机制和来源后，必须在与档案类型相应的位置设置档案。.NET/C# 驱动程序会按此处列出的顺序检查以下位置的档案：

Web 身份提供程序
共享的 AWS 凭证文件
环境变量
ECS 容器档案
EC2 容器档案

您可以使用与 OpenID Connect (OIDC) 兼容的 Web 身份提供者 对 Amazon Elastic Kubernetes Service (EKS) 或其他服务进行身份验证。要使用 Web 身份提供者，请创建一个包含 OIDC 令牌的文件，然后使用 bash 或类似的 shell 在环境变量中设置该文件的绝对路径，如以下示例所示：

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>

要使用共享 AWS 档案文件中的配置文件进行身份验证，可以使用文本编辑器、适用于 .NET 的 AWS SDK 或 AWS CLI 创建适当的档案文件。

若要直接从环境变量中检索档案，请使用 bash 或类似的 Shell 设置以下环境变量：

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

注意

如果您不需要该角色的 AWS 会话令牌，请省略包含AWS_SESSION_TOKEN的行。

要使用 ECS container 档案进行身份验证，请使用 bash 或类似的 shell 在环境变量中设置 ECS 终端节点的 URI。选择 Full ECS URI 或 Relative ECS URI 标签页，查看指定相应环境变量的语法：

export AWS_CONTAINER_CREDENTIALS_FULL_URI=<full ECS endpoint>

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<relative ECS endpoint>

要使用 EC2 容器档案进行身份验证，确保未设置前面提到的任何环境变量。驱动程序会从默认 IPv4 EC2 实例元数据端点获取档案。

x.509

X.509身份验证机制使用 TLS 使用X.509 证书对用户进行身份验证，并由客户端证书的标识名进行标识。当您指定X.509身份验证机制时，服务器将使用客户端证书的主题名称对连接进行身份验证。

要了解有关使用 TLS/SSL 的更多信息，请参阅我们的 TLS/SSL 指南。

要学习；了解有关X.509证书的更多信息，请参阅《 X. 509服务器手册条目》。

选择 Connection String 或 MongoCredential 标签页，查看用于指定Connection String身份验证机制的相应事务语法：

var connectionString = "mongodb://<hostname>/?authMechanism=MONGODB-X509";
var settings = MongoClientSettings.FromConnectionString(connectionString);
settings.useTls = true;
settings.SslSettings = new SslSettings
{
   ClientCertificates = new List<X509Certificate>()
   {
       new X509Certificate2("<path to X.509 certificate>", "<X.509 certificate password>")
   }
};

var credential = MongoCredential.CreateMongoX509Credential("<X.509 certificate username>")
var settings = new MongoClientSettings
{
    Credential =  credential
    SslSettings = new SslSettings
    {
        ClientCertificates = new List<X509Certificate>()
        {
            new X509Certificate2("<path to X.509 certificate>", "<X.509 certificate password>")
        },
    },
    UseTls = true,
    Server = new MongoServerAddress("<hostname", "<port>"),
};

注意

证书类型

您的证书必须是 PKCS #12 类型证书，扩展名为.p12 。

提示

Username parameter

提供给CreateMongoX509Credential的用户名参数必须与X.509证书的标识主题名称完全匹配。您也可以将null作为参数传递，以提示MongoDB服务器根据您的X.509证书推断用户名。

注意

如果您使用的是Windows，驾驶员可能无法找到在内存中创建的X.509身份验证证书。要学习；了解此问题的潜在解决方案，请参阅《连接故障排除指南》中的X. 509凭证错误部分。

API 文档

要进一步了解本指南所讨论的任何方法或类型，请参阅以下 API 文档：

后退

Stable API

来年

企业身份验证机制

身份验证机制.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Overview

指定身份验证机制

机制

默认

注意

SCRAM-SHA-256

提示

默认机制

SCRAM-SHA-1

提示

默认机制

MONGODB-AWS

注意

提示

指定 AWS IAM 凭证

自动检索档案

注意

x.509

注意

证书类型

提示

Username parameter

注意

API 文档

身份验证机制