DOCSP-48166: Async examples for Security pages (#237)

mcmorisi · web-flow · commit e6994501900e · 2025-03-26T10:13:25.000-04:00
diff --git a/source/includes/authentication/azure-envs-mongoclient-async.py b/source/includes/authentication/azure-envs-mongoclient-async.py
@@ -0,0 +1,18 @@
+from pymongo import AsyncMongoClient
+from azure.identity import DefaultAzureCredential
+from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult
+         
+# define callback, properties, and MongoClient
+audience = "<audience>"
+client_id = "<Azure 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 = AsyncMongoClient(
+   "mongodb[+srv]://<hostname>:<port>",
+   authMechanism="MONGODB-OIDC",
+   authMechanismProperties=properties
+)
diff --git a/source/includes/authentication/azure-imds-connection-string-async.py b/source/includes/authentication/azure-imds-connection-string-async.py
@@ -0,0 +1,8 @@
+from pymongo import AsyncMongoClient
+
+# define URI and MongoClient
+uri = ("mongodb[+srv]://<hostname>:<port>/?"
+       "username=<username>"
+       "&authMechanism=MONGODB-OIDC"
+       "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
+client = AsyncMongoClient(uri)
diff --git a/source/includes/authentication/azure-imds-mongoclient-async.py b/source/includes/authentication/azure-imds-mongoclient-async.py
@@ -0,0 +1,10 @@
+from pymongo import AsyncMongoClient
+
+# define properties and MongoClient
+properties = {"ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>"}
+client = AsyncMongoClient(
+    "mongodb[+srv]://<hostname>:<port>",
+    username="<Azure ID>",
+    authMechanism="MONGODB-OIDC",
+    authMechanismProperties=properties
+)
diff --git a/source/includes/authentication/gcp-gke-mongoclient-async.py b/source/includes/authentication/gcp-gke-mongoclient-async.py
@@ -0,0 +1,15 @@
+from pymongo import AsyncMongoClient
+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 = AsyncMongoClient(
+   "mongodb[+srv]://<hostname>:<port>",
+   authMechanism="MONGODB-OIDC",
+   authMechanismProperties=properties
+)
diff --git a/source/includes/authentication/gcp-imds-connection-string-async.py b/source/includes/authentication/gcp-imds-connection-string-async.py
@@ -0,0 +1,7 @@
+from pymongo import AsyncMongoClient
+
+# define URI and MongoClient
+uri = ("mongodb[+srv]://<hostname>:<port>/?"
+       "&authMechanism=MONGODB-OIDC"
+       "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
+client = AsyncMongoClient(uri)
diff --git a/source/includes/authentication/gcp-imds-mongoclient-async.py b/source/includes/authentication/gcp-imds-mongoclient-async.py
@@ -0,0 +1,9 @@
+from pymongo import AsyncMongoClient
+
+# define properties and MongoClient
+properties = {"ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>"}
+client = AsyncMongoClient(
+   "mongodb[+srv]://<hostname>:<port>",
+   authMechanism="MONGODB-OIDC",
+   authMechanismProperties=properties
+)
diff --git a/source/includes/authentication/kubernetes-connection-string.py b/source/includes/authentication/kubernetes-connection-string.py
@@ -1,8 +1,15 @@
-from pymongo import MongoClient
+from pymongo import MongoClient, AsyncMongoClient
 
 # start-kubernetes-connection-string
 uri = ("mongodb[+srv]://<hostname>:<port>/?"
        "authMechanism=MONGODB-OIDC"
        "&authMechanismProperties=ENVIRONMENT:k8s")
 client = MongoClient(uri)
-# end-kubernetes-connection-string
+# end-kubernetes-connection-string
+
+# start-kubernetes-connection-string-async
+uri = ("mongodb[+srv]://<hostname>:<port>/?"
+       "authMechanism=MONGODB-OIDC"
+       "&authMechanismProperties=ENVIRONMENT:k8s")
+client = AsyncMongoClient(uri)
+# end-kubernetes-connection-string-async
diff --git a/source/includes/authentication/kubernetes-mongoclient.py b/source/includes/authentication/kubernetes-mongoclient.py
@@ -1,4 +1,4 @@
-from pymongo import MongoClient
+from pymongo import MongoClient, AsyncMongoClient
 
 # start-kubernetes-mongoclient
 properties = {"ENVIRONMENT": "k8s"}
@@ -7,4 +7,13 @@
     authMechanism="MONGODB-OIDC",
     authMechanismProperties=properties
 )
-# end-kubernetes-mongoclient
+# end-kubernetes-mongoclient
+
+# start-kubernetes-mongoclient-async
+properties = {"ENVIRONMENT": "k8s"}
+client = AsyncMongoClient(
+    "mongodb[+srv]://<hostname>:<port>",
+    authMechanism="MONGODB-OIDC",
+    authMechanismProperties=properties
+)
+# end-kubernetes-mongoclient-async
diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst
@@ -15,4 +15,21 @@
       .. code-block:: python
 
          uri = "mongodb://<db_username>:<db_password>@<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem"
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsCAFile="/path/to/ca.pem")
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = "mongodb://<db_username>:<db_password@<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem"
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/client-cert-tabs.rst b/source/includes/connect/client-cert-tabs.rst
@@ -17,4 +17,23 @@
          uri = ("mongodb://<db_username>:<db_password>@<hostname:<port>/?"
                 "tls=true"
                 "&tlsCertificateKeyFile=path/to/client.pem")
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsCertificateKeyFile='/path/to/client.pem')
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+                "tls=true"
+                "&tlsCertificateKeyFile=path/to/client.pem")
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs.rst
@@ -15,4 +15,21 @@
       .. code-block:: python
 
          uri = "mongodb://example.com/?tls=true&tlsCRLFile=/path/to/crl.pem"
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsCRLFile="/path/to/crl.pem")
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = "mongodb://example.com/?tls=true&tlsCRLFile=/path/to/crl.pem"
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/disable-cert-validation-tabs.rst b/source/includes/connect/disable-cert-validation-tabs.rst
@@ -17,4 +17,23 @@
          uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
                 "tls=true"
                 "&tlsAllowInvalidCertificates=true")
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsAllowInvalidCertificates=True)
+
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+                "tls=true"
+                "&tlsAllowInvalidCertificates=true")
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/disable-host-verification-tabs.rst b/source/includes/connect/disable-host-verification-tabs.rst
@@ -17,4 +17,23 @@
          uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
                 "tls=true"
                 "&tlsAllowInvalidHostnames=true")
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsAllowInvalidHostnames=True)
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+                "tls=true"
+                "&tlsAllowInvalidHostnames=true")
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst
@@ -17,4 +17,23 @@
          uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
                 "tls=true"
                 "&tlsInsecure=true")
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsInsecure=True)
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+                "tls=true"
+                "&tlsInsecure=true")
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/key-file-password.rst b/source/includes/connect/key-file-password.rst
@@ -19,4 +19,26 @@
                 "tls=true"
                 "&tlsCertificateKeyFile=path/to/client.pem"
                 "&tlsCertificateKeyFilePassword=<passphrase>")
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                       tls=True,
+                                       tlsCertificateKeyFile='/path/to/client.pem',
+                                       tlsCertificateKeyFilePassword=<passphrase>)
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password"
+                "@<hostname>:<port>/?"
+                "tls=true"
+                "&tlsCertificateKeyFile=path/to/client.pem"
+                "&tlsCertificateKeyFilePassword=<passphrase>")
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/ocsp-tabs.rst b/source/includes/connect/ocsp-tabs.rst
@@ -15,4 +15,21 @@
       .. code-block:: python
 
          uri = "mongodb://example.com/?tls=true&tlsDisableOCSPEndpointCheck=true"
-         client = pymongo.MongoClient(uri)
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+                                           tls=True,
+                                           tlsDisableOCSPEndpointCheck=True)
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = "mongodb://example.com/?tls=true&tlsDisableOCSPEndpointCheck=true"
+         client = pymongo.AsyncMongoClient(uri)
diff --git a/source/includes/connect/tls-tabs.rst b/source/includes/connect/tls-tabs.rst
@@ -12,4 +12,18 @@
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true")
+         client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true")
+
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>", tls=True)
+   
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>?tls=true")
diff --git a/source/security.txt b/source/security.txt
diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt
diff --git a/source/security/authentication/kerberos.txt b/source/security/authentication/kerberos.txt
diff --git a/source/security/authentication/ldap.txt b/source/security/authentication/ldap.txt
diff --git a/source/security/authentication/oidc.txt b/source/security/authentication/oidc.txt
diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt
diff --git a/source/security/authentication/x509.txt b/source/security/authentication/x509.txt
