Docs Menu
Docs Home
/
Languages
/
C Driver
/
C Driver
/
Secure Your Data

Authentication Mechanisms

On this page

  • Overview
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-X509
  • MONGODB-AWS
  • Connection URI
  • Environment Variables
  • ECS Metadata
  • EC2 Instance Metadata
  • API Documentation

Overview

This guide describes the mechanisms you can use in the C driver to authenticate users to MongoDB.

Important

Percent-Encoding

You must percent-encode a username and password before you include them in a MongoDB URI.

SCRAM-SHA-256

SCRAM-SHA-256, as defined by RFC 7677, is the default authentication mechanism on MongoDB deployments running MongoDB v4.0 or later.

To authenticate by using SCRAM-SHA-256, set the following connection options:

  • username: The username to authenticate. Percent-encode this value before including it in the connection URI.

  • password: The password to authenticate. Percent-encode this value before including it in the connection URI.

  • authSource: The MongoDB database to authenticate against. By default, the C driver authenticates against the database in the connection URI, if you include one. If you don't specify an authentication database, it authenticates against the admin database.

  • authMechanism: Set to SCRAM-SHA-256.

You can set these options by using parameters in your connection string, as shown in the following code example:

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, as defined by RFC 5802, is the default authentication mechanism on MongoDB deployments running MongoDB v3.6.

To authenticate with this mechanism, set the following connection options:

  • username: The username to authenticate. Percent-encode this value before including it in the connection URI.

  • password: The password to authenticate. Percent-encode this value before including it in the connection URI.

  • authSource: The MongoDB database to authenticate against. By default, the C driver authenticates against the admin database.

  • authMechanism: Set to "SCRAM-SHA-1".

You can set these options by using parameters in your connection string, as shown in the following code example:

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

If you compile the C driver with TLS support, the C driver can present an X.509 client certificate to MongoDB to prove its identity during the TLS handshake. The MONGODB-X509 authentication mechanism uses this certificate to authenticate the client.

To authenticate with this mechanism, perform the following steps:

  1. Create a mongoc_ssl_opt_t structure. On this structure, set the pem_file field to the file path of the .pem file that contains your client certificate and private key.

  2. In your connection URI, set the authMechanism connection option to "MONGODB-X509".

The following code example shows how to create a MongoDB client that authenticates by using the MONGODB-X509 mechanism:

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

Important

The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later.

The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and Access Management) or AWS Lambda credentials to authenticate your application. To use this mechanism to authenticate your application, first create a user with an associated Amazon Resource Name (ARN) on the $external database. Then, specify the MONGODB-AWS authMechanism in the connection URI.

When you use the MONGODB-AWS mechanism, the C driver attempts to retrieve your AWS credentials from the following sources, in the order listed:

  1. Named parameters passed to the connection URI

  2. Environment variables

  3. AWS EKS AssumeRoleWithWebIdentity request

  4. ECS container metadata

  5. EC2 instance metadata

The following sections describe how to use the C driver to retrieve credentials from these sources and use them to authenticate your application.

Connection URI

First, the C driver checks whether you passed AWS credentials to the mongoc_client_t constructor as part of the connection URI. To pass your credentials in the connection URI, set the following connection options:

  • username: The AWS IAM access key ID to authenticate.

  • password: The AWS IAM secret access key.

  • authMechanism: Set to "MONGODB-AWS".

You can set these options in the connection URI, as shown in the following example:

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);

You can also include an AWS session token by passing it into the authMechanismProperties parameter:

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);

Environment Variables

If you don't include a username and password in your connection URI, the C driver tries to retrieve AWS credentials from the following environment variables:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN (optional)

To use these environment variables to authenticate your application, first set them to the AWS IAM values needed for authentication, as shown in the following code example:

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>

After you set these environment variables, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

ECS Metadata

If your application runs in an Elastic Container Service (ECS) container, the C driver can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

After you set the environment variable, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

EC2 Instance Metadata

The C driver can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the authMechanism parameter in your connection URI to "MONGODB-AWS", as shown in the following example:

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

Note

If you set any of the environment variables from the preceding AWS authentication methods, the C driver attempts to retrieve credentials by using those methods before attempting to retrieve them from an EC2 instance. To attempt to retrieve credentials only from an EC2 instance, ensure that the environment variables are not set.

API Documentation

To learn more about authenticating your application in the C driver, see the following API documentation:

Back

Secure Your Data

Next

Enterprise Authentication Mechanisms