Overview
Esta guía describe los mecanismos que puedes usar en el driver C para autenticar usuarios a MongoDB.
Importante
Codificación porcentaje
Usted debe encode percentualmente un nombre de usuario y contraseña antes de incluirlos en un URI de MongoDB.
SCRAM-SHA-256
SCRAM-SHA-,256 según lo define RFC, es el mecanismo de autenticación predeterminado en las implementaciones de MongoDB que ejecutan 7677MongoDB4 v.0 o posterior.
Para autenticar usando SCRAM-SHA-256, configure las siguientes opciones de conexión:
usernameNombre de usuario para autenticar. Codifique este valor porcentualmente antes de incluirlo en la URI de conexión.passwordContraseña para la autenticación. Codifique este valor porcentualmente antes de incluirlo en la URI de conexión.authSourceLa base de datos MongoDB contra la que se debe autenticar. Por defecto, el controlador C se autentica contra la base de datos en el URI de conexión, si incluye uno. Si no especificas una base de datos de autenticación, se autentica contra la base de datosadmin.authMechanism:Establecer enSCRAM-SHA-256.
Puede configurar estas opciones de conexión mediante una cadena de conexión o la API mongoc_uri_t. El siguiente ejemplo de código muestra cómo crear un cliente MongoDB que se autentica mediante el mecanismo SCRAM-SHA-256:
const char *uri = "mongodb://<percentEncodedUsername>:<percentEncodedPassword>@<hostname>:<port>/?authMechanism=SCRAM-SHA-256&authSource=<authenticationDatabase>"; mongoc_client_t *client = mongoc_client_new(uri);
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<percentEncodedUsername>:<percentEncodedPassword>@<hostname>:<port>/"); // Set the authentication mechanism and properties mongoc_uri_set_auth_mechanism(uri, "SCRAM-SHA-256"); mongoc_uri_set_auth_source(uri, "<authenticationDatabase>"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
SCRAM-SHA-1
SCRAM-SHA-1, como se define en RFC 5802 es el mecanismo de autenticación predeterminado en implementaciones de MongoDB que ejecutan MongoDB v3.6.
Para autenticarte con este mecanismo, establece las siguientes opciones de conexión:
usernameNombre de usuario para autenticar. Codifique este valor porcentualmente antes de incluirlo en la URI de conexión.passwordContraseña para la autenticación. Codifique este valor porcentualmente antes de incluirlo en la URI de conexión.authSource: La base de datos de MongoDB ante la que se debe autenticar. Por defecto, el controlador C se autentica contra la base de datosadmin.authMechanism:Establecer en"SCRAM-SHA-1".
Puede configurar estas opciones de conexión mediante una cadena de conexión o la API mongoc_uri_t. El siguiente ejemplo de código muestra cómo crear un cliente MongoDB que se autentica mediante el mecanismo SCRAM-SHA-1:
const char *uri = "mongodb://<percentEncodedUsername>:<percentEncodedPassword>@<hostname>:<port>/?authMechanism=SCRAM-SHA-1&authSource=<authenticationDatabase>"; mongoc_client_t *client = mongoc_client_new(uri);
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<percentEncodedUsername>:<percentEncodedPassword>@<hostname>:<port>/"); // Set the authentication mechanism and properties mongoc_uri_set_auth_mechanism(uri, "SCRAM-SHA-1"); mongoc_uri_set_auth_source(uri, "<authenticationDatabase>"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
MONGODB-X509
Si compila el controlador C con compatibilidad con TLS, este puede presentar un certificado de cliente X.509 a MongoDB para comprobar su identidad durante el protocolo de enlace TLS. El mecanismo de autenticación de MONGODB-X509 utiliza este certificado para autenticar al cliente.
Para autenticarte con este mecanismo, realiza los siguientes pasos:
Crea una estructura
mongoc_ssl_opt_t. En esta estructura, establece el campopem_fileen la ruta del archivo.pemque contiene tu certificado de cliente y llave privada.En su URI de conexión, establezca la opción de conexión
authMechanismen"MONGODB-X509".
Puede configurar este método de autenticación utilizando una cadena de conexión o la mongoc_uri_t API. El siguiente ejemplo de código muestra cómo crear un cliente de MongoDB que se autentica utilizando el mecanismo MONGODB-X509:
mongoc_client_t *client; mongoc_ssl_opt_t ssl_opts = {0}; ssl_opts.pem_file = "mycert.pem"; const char *uri = "mongodb://<percentEncodedUsername>@<hostname>:<port>/?authMechanism=MONGODB-X509"; mongoc_client_t *client = mongoc_client_new(uri); mongoc_client_set_ssl_opts(client, &ssl_opts);
mongoc_client_t *client; mongoc_ssl_opt_t ssl_opts = {0}; ssl_opts.pem_file = "mycert.pem"; mongoc_uri_t *uri = mongoc_uri_new("mongodb://<percentEncodedUsername>:<percentEncodedPassword>@<hostname>:<port>/"); // Set the authentication mechanism mongoc_uri_set_auth_mechanism(uri, "MONGODB-X509"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri); mongoc_client_set_ssl_opts(client, &ssl_opts);
MONGODB-AWS
Importante
El mecanismo de autenticación MONGODB-AWS requiere MongoDB v4.4 o posterior.
El mecanismo de autenticación MONGODB-AWS utiliza AWS IAM (Amazon Web Services Identity and Access Management) o credenciales de AWS Lambda para autenticar tu aplicación. Para utilizar este mecanismo para autenticar su aplicación, primero cree un usuario con un Amazon Resource Name (ARN) asociado en la base de datos $external. A continuación, especifique el MONGODB-AWS authMechanism en la URI de conexión.
Cuando utiliza el mecanismo MONGODB-AWS, el controlador C intenta recuperar sus credenciales de AWS de las siguientes fuentes, en el orden indicado:
Parámetros nombrados pasados a la URI de conexión
Variables de entorno
Solicitud AssumeRoleWithWebIdentity de AWS EKS
Metadatos de contenedor ECS
Metadatos de la instancia EC2
Las siguientes secciones describen cómo usar el controlador C para recuperar credenciales de estas fuentes y utilizarlas para autenticar su aplicación.
URI de conexión
Primero, el controlador C verifica si pasaste credenciales AWS al constructor mongoc_client_t como parte del URI de conexión. Para pasar tus credenciales en el URI de conexión, establece las siguientes opciones de conexión:
username: La clave de acceso de AWS IAM para autenticar.password: La clave de acceso secreta de AWS IAM.authMechanism:Establecer en"MONGODB-AWS".
Puede crear un URI que contenga estas opciones de conexión utilizando una cadena de conexión o la API mongoc_uri_t. El siguiente ejemplo de código muestra cómo crear un cliente de MongoDB que se autentique utilizando el mecanismo MONGODB-AWS:
const char *uri = "mongodb://<awsIamAccessKeyId>:<awsIamSecretAccessKey>@<hostname>:<port>/?authMechanism=MONGODB-AWS"; mongoc_client_t *client = mongoc_client_new(uri);
También puedes incluir un token de sesión de AWS pasándolo al parámetro authMechanismProperties:
const char *uri = "mongodb://<awsIamAccessKeyId>:<awsIamSecretAccessKey>@<hostname>:<port>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<token>"; mongoc_client_t *client = mongoc_client_new(uri);
Importante
No puedes especificar un valor de propiedad que contenga el carácter coma (,) como una opción de cadena de conexión authMechanismProperties, incluso cuando el carácter coma está por ciento-codificado. Para especificar un valor de propiedad authMechanismProperties que contenga una coma, se debe establecer la opción utilizando el método mongoc_uri_set_mechanism_properties().
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<awsIamAccessKeyId>:<awsIamSecretAccessKey>@<hostname>:<port>/"); // Set the authentication mechanism mongoc_uri_set_auth_mechanism(uri, "MONGODB-AWS"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
También puedes incluir un token de sesión de AWS pasándolo al parámetro authMechanismProperties:
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<awsIamAccessKeyId>:<awsIamSecretAccessKey>@<hostname>:<port>/"); // Set the authentication mechanism and properties mongoc_uri_set_auth_mechanism(uri, "MONGODB-AWS"); bson_t mechanism_properties = BSON_INITIALIZER; BSON_APPEND_UTF8(&mechanism_properties, "AWS_SESSION_TOKEN", "<token>"); mongoc_uri_set_mechanism_properties(uri, &mechanism_properties) // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
Variables de entorno
Si no incluyes un nombre de usuario y una contraseña en tu URI de conexión, el controlador de C intenta recuperar las credenciales de AWS de las siguientes variables de entorno:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN(opcional)
Para usar estas variables de entorno para autenticar su aplicación, primero configúrelas con los valores de AWS IAM necesarios para la autenticación, como se muestra en el siguiente ejemplo de código:
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>
Después de que establezca estas variables de entorno, establezca el parámetro authMechanism en su URI de conexión a "MONGODB-AWS" utilizando ya sea una cadena de conexión o la API mongoc_uri_t, como se muestra en el siguiente ejemplo:
const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS"; mongoc_client_t *client = mongoc_client_new(uri);
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<hostname>:<port>/"); // Set the authentication mechanism mongoc_uri_set_auth_mechanism(uri, "MONGODB-AWS"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
ECS Metadata
Si su aplicación se ejecuta en un contenedor Elastic Container Service (ECS), el driver C puede recuperar automáticamente credenciales temporales de AWS desde un endpoint ECS. Para ello, especifique la URI del endpoint ECS en una variable de entorno llamada AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, como se muestra en el siguiente ejemplo:
export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>
Después de configurar la variable de entorno, configura el parámetro authMechanism en tu URI de conexión a "MONGODB-AWS" usando una cadena de conexión o la API mongoc_uri_t, como se muestra en el siguiente ejemplo:
const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS"; mongoc_client_t *client = mongoc_client_new(uri);
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<hostname>:<port>/"); // Set the authentication mechanism mongoc_uri_set_auth_mechanism(uri, "MONGODB-AWS"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
Metadatos de instancia EC2
El controlador C puede recuperar automáticamente las credenciales temporales de AWS desde una instancia de Amazon Elastic Cloud Compute (EC2). Para usar las credenciales temporales desde una instancia de EC2, configure el parámetro authMechanism en la URI de conexión como "MONGODB-AWS" mediante una cadena de conexión o la API mongoc_uri_t, como se muestra en el siguiente ejemplo:
const char *uri = "mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS"; mongoc_client_t *client = mongoc_client_new(uri);
mongoc_uri_t *uri = mongoc_uri_new("mongodb://<hostname>:<port>/"); // Set the authentication mechanism mongoc_uri_set_auth_mechanism(uri, "MONGODB-AWS"); // Create a client from the URI mongoc_client_t *client = mongoc_client_new_from_uri(uri);
Nota
Si configuras cualquiera de las variables de entorno de los métodos de autenticación AWS anteriores, el driver C intenta recuperar credenciales utilizando esos métodos antes de intentar recuperarlas de una instancia EC2. Para intentar recuperar credenciales solo de una instancia EC2, asegúrese de que las variables de entorno no estén configuradas.
OIDC
El mecanismo de autenticación OpenID Connect (OIDC) permite autenticarse en MongoDB usando un proveedor de identidad de terceros, como Azure o Google Cloud Platform (GCP).
Puedes utilizar este mecanismo solo al autenticarte en MongoDB Atlas o MongoDB Enterprise Advanced, y solo al autenticarte en MongoDB Server v7.0 o posterior.
Tip
Autenticación OIDC
Para obtener más información sobre cómo configurar MongoDB Atlas para la autenticación OIDC, consulta Configurar la Federación de Identidad de la Fuerza Laboral con OIDC en el manual de MongoDB Server.
Para obtener más información sobre el uso de la autenticación OIDC con MongoDB, consulta Autenticación OpenID Connect y Parámetros del MongoDB Server en el manual del MongoDB Server.
Las siguientes secciones describen cómo utilizar la autenticación OIDC para autenticarse desde varias plataformas.
Azure
Si tu aplicación se ejecuta en una máquina virtual de Azure, o de otro modo utiliza el Servicio de Metadatos de Instancia de Azure (IMDS), puedes autenticarte en MongoDB utilizando el soporte de funcionalidad incorporada de Azure del driver C.
El siguiente ejemplo inicializa un mongoc_client_t que utiliza la autenticación OIDC con Azure:
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
Si tu aplicación se ejecuta en una máquina virtual de Google Compute Engine o utiliza de otro modo el Servicio de metadatos de instancia de GCP, puedes autenticarte en MongoDB utilizando el soporte de funcionalidad incorporada de GCP del controlador C.
El siguiente ejemplo inicializa un mongoc_client_t que utiliza la autenticación OIDC con GCP:
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; }
Función de retorno personalizado
También puedes proporcionar una función de retorno personalizada para recuperar un token OIDC de tu proveedor de identidad, como se muestra en el siguiente ejemplo:
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; }
Documentación de la API
Para aprender más sobre cómo autenticar tu aplicación en el driver C, consulta la siguiente documentación de la API: