From b83fd991feda9819b4d40efcf7c055c517c16be9 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Mon, 29 Apr 2024 13:22:14 -0500 Subject: [PATCH] PYTHON-3601 OIDC: Clarify TOKEN_RESOURCE and client_id usage (#1621) Co-authored-by: Mike Woofter <108414937+mongoKart@users.noreply.github.com> --- doc/examples/authentication.rst | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/doc/examples/authentication.rst b/doc/examples/authentication.rst index cac9d49a91..24b3cff8df 100644 --- a/doc/examples/authentication.rst +++ b/doc/examples/authentication.rst @@ -408,8 +408,10 @@ Azure IMDS ^^^^^^^^^^ For an application running on an Azure VM or otherwise using the `Azure Internal Metadata Service`_, -you can use the built-in support for Azure, where "" below is the client id of the Azure -managed identity, and ```` is the url-encoded ``audience`` `configured on your MongoDB deployment`_. +you can use the built-in support for Azure. If using an Azure managed identity, the "" is +the client ID. If using a service principal to represent an enterprise application, the "" is +the application ID of the service principal. The ```` value is the ``audience`` +`configured on your MongoDB deployment`_. .. code-block:: python @@ -430,11 +432,24 @@ managed identity, and ```` is the url-encoded ``audience`` `configured If the application is running on an Azure VM and only one managed identity is associated with the VM, ``username`` can be omitted. +If providing the ``TOKEN_RESOURCE`` as part of a connection string, it can be given as follows. +If the ``TOKEN_RESOURCE`` contains any of the following characters [``,``, ``+``, ``&``], then +it MUST be url-encoded. + +.. code-block:: python + + import os + + uri = f'{os.environ["MONGODB_URI"]}?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:' + c = MongoClient(uri) + c.test.test.insert_one({}) + c.close() + GCP IMDS ^^^^^^^^ For an application running on an GCP VM or otherwise using the `GCP Internal Metadata Service`_, -you can use the built-in support for GCP, where ```` below is the url-encoded ``audience`` +you can use the built-in support for GCP, where ```` below is the ``audience`` `configured on your MongoDB deployment`_. .. code-block:: python @@ -448,6 +463,18 @@ you can use the built-in support for GCP, where ```` below is the url- c.test.test.insert_one({}) c.close() +If providing the ``TOKEN_RESOURCE`` as part of a connection string, it can be given as follows. +If the ``TOKEN_RESOURCE`` contains any of the following characters [``,``, ``+``, ``&``], then +it MUST be url-encoded. + +.. code-block:: python + + import os + + uri = f'{os.environ["MONGODB_URI"]}?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:' + c = MongoClient(uri) + c.test.test.insert_one({}) + c.close() Custom Callbacks ~~~~~~~~~~~~~~~~