/ /

身份验证机制

Overview

本指南介绍了可在C驱动程序中用于对MongoDB用户进行身份验证的机制。

重要

百分比编码

在将用户名和密码包含在MongoDB URI 中之前，必须对用户名和密码进行百分比编码。

SCRAM-SHA-256

SCRAM-SHA-256（如RFC 7677所定义）是运行MongoDB v4.0 的MongoDB部署上的默认身份验证机制。或更高版本。

要使用SCRAM-SHA-256 进行身份验证，设立以下连接选项：

username：要进行身份验证的用户名。在将其包含在连接 URI 中之前，对该值进行百分比编码。
password：用于身份验证的密码。在将其包含在连接 URI 中之前，对该值进行百分比编码。
authSource: 要进行身份验证的 MongoDB 数据库。默认下， C驱动程序根据连接 URI 中的数据库（如果包含数据库）进行身份验证。如果不指定身份验证数据库，则会根据 admin数据库进行身份验证。
authMechanism：设置为SCRAM-SHA-256 。

您可以使用连接字符串中的参数来设立这些选项，如以下代码示例所示：

const char *uri = "mongodb://<percent-encoded username>:<percent-encoded password>@<hostname>:<port>/?authMechanism=SCRAM-SHA-256&authSource=<authentication database>";
mongoc_client_t *client = mongoc_client_new(uri);

SCRAM-SHA-1

SCRAM-SHA-1（如RFC 5802所定义）是运行MongoDB v3.6 的MongoDB部署上的默认身份验证机制。

要使用此机制进行身份验证，请设置以下连接选项：

username：要进行身份验证的用户名。在将其包含在连接 URI 中之前，对该值进行百分比编码。
password：用于身份验证的密码。在将其包含在连接 URI 中之前，对该值进行百分比编码。
authSource: 要进行身份验证的 MongoDB 数据库。默认下，C 驱动程序根据 admin数据库进行身份验证。
authMechanism：设置为"SCRAM-SHA-1" 。

您可以使用连接字符串中的参数来设立这些选项，如以下代码示例所示：

const char *uri = "mongodb://<percent-encoded username>:<percent-encoded password>@<hostname>:<port>/?authMechanism=SCRAM-SHA-1&authSource=<authentication database>";
mongoc_client_t *client = mongoc_client_new(uri);

MONGODB-X509

如果编译支持 TLS 的 C 驱动程序，则 C 驱动程序可以向 MongoDB 提供 X.509 客户端证书，以在 TLS 握手期间证明其身份。MONGODB-X509身份验证机制使用此证书对客户端进行身份验证。

要使用此机制进行身份验证，请执行以下步骤：

创建 mongoc_ssl_opt_t 结构。在此结构中，将 pem_file字段设立为包含客户端证书和私钥的 .pem文件的文件路径。
在连接 URI 中，将 authMechanism 连接选项设立为 "MONGODB-X509"。

以下代码示例展示了如何创建使用 MONGODB-X509 机制进行身份验证的MongoDB客户端：

mongoc_client_t *client;
mongoc_ssl_opt_t ssl_opts = {0};
ssl_opts.pem_file = "mycert.pem";
const char *uri = "mongodb://<percent-encoded username>@<hostname>:<port>/?authMechanism=MONGODB-X509";
mongoc_client_t *client = mongoc_client_new(uri);
mongoc_client_set_ssl_opts(client, &ssl_opts);

MONGODB-AWS

重要

MONGODB-AWS 身份验证机制需要 MongoDB v 4.4或更高版本。

MONGODB-AWS身份验证机制使用Amazon Web Services IAM（Amazon Web Services身份和访问管理）或Amazon Web Services Lambda凭证对应用程序进行身份验证。要使用此机制对应用程序进行身份验证，请先在 $external数据库上创建一个具有关联Amazon资源名称 (ARN) 的用户。然后，在连接 URI 中指定 MONGODB-AWS authMechanism。

当您使用 MONGODB-AWS 机制时， C驱动程序会尝试按列出的顺序从以下源检索您的 AWS凭证：

传递给连接 URI 的命名参数
环境变量
Amazon Web Services EKS AssumeRoleWithWebIdentity请求
ECS容器元数据
EC 2实例元数据

以下部分介绍如何使用C驱动程序从这些来源检索凭证，并使用它们对应用程序进行身份验证。

连接 URI

首先， C驱动程序会检查您是否将 AWS凭证作为连接 URI 的一部分传递给 mongoc_client_t 构造函数。要在连接 URI 中传递凭证，设立以下连接选项：

username：要进行身份验证的Amazon Web Services IAM访问权限密钥ID 。
password： Amazon Web Services IAM 秘密访问权限密钥。
authMechanism：设置为"MONGODB-AWS" 。

您可以在连接 URI 中设立这些选项，如以下示例所示：

const char *uri = "mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS");
mongoc_client_t *client = mongoc_client_new(uri);

您还可以通过将Amazon Web Services会话令牌传递给 authMechanismProperties 参数来包含该令牌：

const char *uri = "mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>");
mongoc_client_t *client = mongoc_client_new(uri);

重要

即使逗号字符是百分号编码的，也不能将包含逗号 (,) 字符的属性值指定为 authMechanismProperties连接字符串选项。要指定包含逗号的 authMechanismProperties属性值，请使用 mongoc_uri_set_mechanism_properties() 方法设立该选项。

环境变量

如果您未在连接 URI 中包含用户名和密码， C驱动程序会尝试从以下环境变量中检索AWS凭证：

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN （可选）

要使用这些环境变量对应用程序进行身份验证，请先将它们设置为身份验证所需的Amazon Web Services IAM 值，如以下代码示例所示：

export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
export AWS_SESSION_TOKEN=<AWS session token>

设立这些环境变量后，将连接 URI 中的authMechanism参数设立为"MONGODB-AWS" ，如以下示例所示：

const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS");
mongoc_client_t *client = mongoc_client_new(uri);

ECS Metadata

如果您的应用程序在弹性容器服务 (ECS) 容器中运行，则 C 驱动程序可以自动从 ECS 终结点检索临时 AWS 凭证。为此，在名为 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 的环境变量中指定 ECS 终结点的 URI，如以下示例所示：

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

设立环境变量后，将连接 URI 中的authMechanism参数设立为"MONGODB-AWS" ，如以下示例所示：

const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS");
mongoc_client_t *client = mongoc_client_new(uri);

EC 2实例元数据

C驱动程序可以自动从Amazon Elastic Cloud Compute (EC2)实例检索临时 AWS凭证。要使用 EC2实例中的临时凭证，请将连接 URI 中的 authMechanism 参数设立为 "MONGODB-AWS"，如以下示例所示：

const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS");
mongoc_client_t *client = mongoc_client_new(uri);

注意

如果您通过上述 AWS 身份验证方法设立了任何环境变量，则 C 驱动程序会先尝试使用这些方法检索凭证，然后再尝试从 EC2 实例中检索凭证。要尝试仅从 EC2实例检索凭证，请确保未设立环境变量。

OIDC

OpenID Connect (OIDC)身份验证机制允许您使用第三方身份提供商（例如Azure或Google Cloud Platform (GCP )）向MongoDB进行身份验证。

只有在向MongoDB Atlas或MongoDB Enterprise Advanced进行身份验证时，并且只有在向MongoDB Server v7.0 或更高版本进行身份验证时，才能使用此机制。

提示

OIDC 身份验证

要学习；了解有关为 OIDC身份验证配置MongoDB Atlas 的更多信息，请参阅MongoDB Server手册中的使用 OIDC 设置劳动力身份联合。

有关在MongoDB中使用 OIDC身份验证的更多信息，请参阅MongoDB Server手册中的 OpenID Connect 身份验证和MongoDB Server参数。

以下部分介绍如何使用 OIDC身份验证从各种平台进行身份验证。

AZURE

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

以下示例初始化使用Azure OIDC身份验证的 mongoc_client_t：

#include <mongoc/mongoc.h>
#define ASSERT_WITH_ERROR(stmt, err)                                                \
   if (!(stmt)) {                                                                   \
      fprintf(stderr, "Error on line %d (%s): %s\n", __LINE__, #stmt, err.message); \
      abort();                                                                      \
   }
#define ASSERT(stmt)                                               \
   if (!(stmt)) {                                                  \
      fprintf(stderr, "Error on line %d (%s)\n", __LINE__, #stmt); \
      abort();                                                     \
   }
int main(void)
{
   bson_error_t error;
   // Create client configured with Azure OIDC:
   mongoc_client_t *client;
   {
      mongoc_uri_t *uri = mongoc_uri_new_with_error(getenv("MONGODB_URI"), &error);
      ASSERT_WITH_ERROR(uri, error);
      mongoc_uri_set_auth_mechanism(uri, "MONGODB-OIDC");
      bson_t mechanism_properties = BSON_INITIALIZER;
      BSON_APPEND_UTF8(&mechanism_properties, "ENVIRONMENT", "azure");
      BSON_APPEND_UTF8(&mechanism_properties, "TOKEN_RESOURCE", "<managed_identity_client_id>");
      ASSERT(mongoc_uri_set_mechanism_properties(uri, &mechanism_properties));
      client = mongoc_client_new_from_uri_with_error(uri, &error);
      ASSERT_WITH_ERROR(client, error);
      bson_destroy(&mechanism_properties);
      mongoc_uri_destroy(uri);
   }
   // Insert a document:
   {
      bson_t doc = BSON_INITIALIZER;
      mongoc_collection_t *coll = mongoc_client_get_collection(client, "db", "coll");
      ASSERT_WITH_ERROR(mongoc_collection_insert_one(coll, &doc, NULL, NULL, &error), error);
      mongoc_collection_destroy(coll);
   }
   mongoc_client_destroy(client);
   return 0;
}

GCP

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

以下示例初始化使用 OIDC身份验证和GCP 的mongoc_client_t：

#include <mongoc/mongoc.h>
#define ASSERT_WITH_ERROR(stmt, err)                                                \
   if (!(stmt)) {                                                                   \
      fprintf(stderr, "Error on line %d (%s): %s\n", __LINE__, #stmt, err.message); \
      abort();                                                                      \
   }
#define ASSERT(stmt)                                               \
   if (!(stmt)) {                                                  \
      fprintf(stderr, "Error on line %d (%s)\n", __LINE__, #stmt); \
      abort();                                                     \
   }
int main(void)
{
   bson_error_t error;
   // Create client configured with GCP OIDC:
   mongoc_client_t *client;
   {
      mongoc_uri_t *uri = mongoc_uri_new_with_error(getenv("MONGODB_URI"), &error);
      ASSERT_WITH_ERROR(uri, error);
      mongoc_uri_set_auth_mechanism(uri, "MONGODB-OIDC");
      bson_t mechanism_properties = BSON_INITIALIZER;
      BSON_APPEND_UTF8(&mechanism_properties, "ENVIRONMENT", "gcp");
      BSON_APPEND_UTF8(&mechanism_properties, "TOKEN_RESOURCE", "<managed_identity_client_id>");
      ASSERT(mongoc_uri_set_mechanism_properties(uri, &mechanism_properties));
      client = mongoc_client_new_from_uri_with_error(uri, &error);
      ASSERT_WITH_ERROR(client, error);
      bson_destroy(&mechanism_properties);
      mongoc_uri_destroy(uri);
   }
   // Insert a document:
   {
      bson_t doc = BSON_INITIALIZER;
      mongoc_collection_t *coll = mongoc_client_get_collection(client, "db", "coll");
      ASSERT_WITH_ERROR(mongoc_collection_insert_one(coll, &doc, NULL, NULL, &error), error);
      mongoc_collection_destroy(coll);
   }
   mongoc_client_destroy(client);
   return 0;
}

自定义回调

您还可以提供自定义回调函数，从身份提供商程序检索OIDC 令牌，如以下示例所示：

#include <mongoc/mongoc.h>
#define ASSERT_WITH_ERROR(stmt, err)                                                \
   if (!(stmt)) {                                                                   \
      fprintf(stderr, "Error on line %d (%s): %s\n", __LINE__, #stmt, err.message); \
      abort();                                                                      \
   }
#define ASSERT(stmt)                                               \
   if (!(stmt)) {                                                  \
      fprintf(stderr, "Error on line %d (%s)\n", __LINE__, #stmt); \
      abort();                                                     \
   }
static mongoc_oidc_credential_t *
oidc_callback_fn(mongoc_oidc_callback_params_t *params)
{
   FILE *token_file = fopen("/tmp/tokens/test_machine", "r");
   ASSERT(token_file);
   // Determine length of token:
   ASSERT(0 == fseek(token_file, 0, SEEK_END));
   long token_len = ftell(token_file);
   ASSERT(token_len > 0);
   ASSERT(0 == fseek(token_file, 0, SEEK_SET));
   // Read file into buffer:
   char *token = bson_malloc(token_len + 1);
   size_t nread = fread(token, 1, token_len, token_file);
   ASSERT(nread == (size_t)token_len);
   token[token_len] = '\0';
   fclose(token_file);
   mongoc_oidc_credential_t *cred = mongoc_oidc_credential_new(token);
   bson_free(token);
   return cred;
}
int main(void)
{
   bson_error_t error;
   // Create client configured with OIDC callback:
   mongoc_client_t *client;
   {
      mongoc_uri_t *uri = mongoc_uri_new_with_error(getenv("MONGODB_URI"), &error);
      ASSERT_WITH_ERROR(uri, error);
      mongoc_uri_set_auth_mechanism(uri, "MONGODB-OIDC");
      mongoc_oidc_callback_t *oidc_callback = mongoc_oidc_callback_new(oidc_callback_fn);
      client = mongoc_client_new_from_uri_with_error(uri, &error);
      ASSERT_WITH_ERROR(client, error);
      ASSERT(mongoc_client_set_oidc_callback(client, oidc_callback));
      mongoc_oidc_callback_destroy(oidc_callback);
      mongoc_uri_destroy(uri);
   }
   // Insert a document:
   {
      bson_t doc = BSON_INITIALIZER;
      mongoc_collection_t *coll = mongoc_client_get_collection(client, "db", "coll");
      ASSERT_WITH_ERROR(mongoc_collection_insert_one(coll, &doc, NULL, NULL, &error), error);
      mongoc_collection_destroy(coll);
   }
   mongoc_client_destroy(client);
   return 0;
}

API 文档

要学习有关在C驱动程序中对应用程序进行身份验证的更多信息，请参阅以下API文档：

后退

TLS 配置

来年

正在使用的加密