Enterprise Authentication Mechanisms

Azure IMDS

If your application runs on an Azure VM, or otherwise uses the Azure Instance Metadata Service (IMDS), you can authenticate to MongoDB by using PyMongo's built-in Azure support.

You can configure OIDC for Azure IMDS in two ways: by passing arguments to the MongoClient constructor or through parameters in your connection string.

properties = {"ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>"}

from pymongo import MongoClient
# define properties and MongoClient
properties = {"ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>"}
client = MongoClient(
    "mongodb://<hostname>:<port>",
    username="<Azure client ID or application ID>",
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=properties
)

from pymongo import MongoClient
# define URI and MongoClient
uri = ("mongodb://<hostname>:<port>/?"
       "username=<Azure client ID or application ID>"
       "&authMechanism=MONGODB-OIDC"
       "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
client = MongoClient(uri)

GCP IMDS

If your application runs on a Google Compute Engine VM, or otherwise uses the GCP Instance Metadata Service, you can authenticate to MongoDB by using PyMongo's built-in GCP support.

You can configure OIDC for GCP IMDS in two ways: by passing arguments to the MongoClient constructor or through parameters in your connection string.

properties = {"ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>"}

from pymongo import MongoClient
# define properties and MongoClient
properties = {"ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>"}
client = MongoClient(
   "mongodb://<hostname>:<port>",
   authMechanism="MONGODB-OIDC",
   authMechanismProperties=properties
)

from pymongo import MongoClient
# define URI and MongoClient
uri = ("mongodb://<hostname>:<port>/?"
       "&authMechanism=MONGODB-OIDC"
       "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
client = MongoClient(uri)

Other Azure Environments

If your application runs on Azure Functions, App Service Environment (ASE), or Azure Kubernetes Service (AKS), you can use the azure-identity package to fetch authentication credentials.

First, use pip to install the azure-identity library, as shown in the following example:

python3 -m pip install azure-identity

Next, define a class that inherits from the OIDCCallback class. This class must implement a fetch() method, which returns the OIDC token in the form of an OIDCCallbackResult object.

The following example shows how to define a callback class named MyCallback. This class includes a fetch() method that retrieves an OIDC token from a file in the standard service-account token-file location.

audience = "<audience>"
client_id = "<Azure client ID>"
class MyCallback(OIDCCallback):
    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        credential = DefaultAzureCredential(managed_identity_client_id=client_id)
        token = credential.get_token(f"{audience}/.default").token
        return OIDCCallbackResult(access_token=token) 

After you define your callback class, create a Python dictionary that contains one key, "OIDC_CALLBACK", whose value is an instance of your custom callback class:

properties = {"OIDC_CALLBACK": MyCallback()}

Finally, set the following connection options by passing arguments to the MongoClient constructor:

• authMechanism: Set to "MONGODB-OIDC".

• authMechanismProperties: Set to the properties dictionary that you created in the previous step.

from pymongo import MongoClient
from azure.identity import DefaultAzureCredential
from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult
         
# define callback, properties, and MongoClient
audience = "<audience>"
client_id = "<Azure client ID>"
class MyCallback(OIDCCallback):
    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        credential = DefaultAzureCredential(managed_identity_client_id=client_id)
        token = credential.get_token(f"{audience}/.default").token
        return OIDCCallbackResult(access_token=token) 
properties = {"OIDC_CALLBACK": MyCallback()}
client = MongoClient(
   "mongodb://<hostname>:<port>",
   authMechanism="MONGODB-OIDC",
   authMechanismProperties=properties
)

GCP GKE

If your application runs on a GCP Google Kubernetes Engine (GKE) cluster with a configured service account, you can read the OIDC token from the standard service-account token-file location.

First, define a class that inherits from the OIDCCallback class. This class must implement a fetch() method, which returns the OIDC token in the form of an OIDCCallbackResult object.

The following example shows how to define a callback class named MyCallback. This class includes a fetch() method that retrieves an OIDC token from a file in the standard service-account token-file location.

class MyCallback(OIDCCallback):
    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        with open("/var/run/secrets/kubernetes.io/serviceaccount/token") as fid:
            token = fid.read()
        return OIDCCallbackResult(access_token=token)

After you define your callback class, create a Python dictionary that contains one key, "OIDC_CALLBACK", whose value is an instance of your custom callback class:

properties = {"OIDC_CALLBACK": MyCallback()}

Finally, set the following connection options by passing arguments to the MongoClient constructor:

• authMechanism: Set to "MONGODB-OIDC".

• authMechanismProperties: Set to the properties dictionary that you created in the previous step.

from pymongo import MongoClient
from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult
         
# define callback, properties, and MongoClient
class MyCallback(OIDCCallback):
    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        with open("/var/run/secrets/kubernetes.io/serviceaccount/token") as fid:
            token = fid.read()
        return OIDCCallbackResult(access_token=token)
properties = {"OIDC_CALLBACK": MyCallback()}
client = MongoClient(
   "mongodb://<hostname>:<port>",
   authMechanism="MONGODB-OIDC",
   authMechanismProperties=properties
)