DOCSP-46651 - Authentication reorganization (#148) (#151)

(cherry picked from commit ec77be0)

Co-authored-by: Mike Woofter <[email protected]>

Author: github-actions[bot]

snooty.toml

@@ -10,6 +10,7 @@ toc_landing_pages = [
     "/aggregation",
     "/aggregation/aggregation-tutorials",
     "/security",
+    "/security/authentication",
     "/aggregation-tutorials",
     "/data-formats",
 ]

source/includes/authentication/azure-envs-mongoclient.py

@@ -4,15 +4,15 @@
 
 # define callback, properties, and MongoClient
 audience = "<audience>"
-client_id = "<Azure client ID>"
+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 = MongoClient(
-   "mongodb://<hostname>:<port>",
+   "mongodb[+srv]://<hostname>:<port>",
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=properties
 )

source/includes/authentication/azure-imds-connection-string.py

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

source/includes/authentication/azure-imds-mongoclient.py

@@ -3,8 +3,8 @@
 # define properties and MongoClient
 properties = {"ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>"}
 client = MongoClient(
-    "mongodb://<hostname>:<port>",
-    username="<Azure client ID or application ID>",
+    "mongodb[+srv]://<hostname>:<port>",
+    username="<Azure ID>",
     authMechanism="MONGODB-OIDC",
     authMechanismProperties=properties
 )

source/includes/authentication/gcp-gke-mongoclient.py

@@ -9,7 +9,7 @@ def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
         return OIDCCallbackResult(access_token=token)
 properties = {"OIDC_CALLBACK": MyCallback()}
 client = MongoClient(
-   "mongodb://<hostname>:<port>",
+   "mongodb[+srv]://<hostname>:<port>",
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=properties
 )

source/includes/authentication/gcp-imds-connection-string.py

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

source/includes/authentication/gcp-imds-mongoclient.py

@@ -3,7 +3,7 @@
 # define properties and MongoClient
 properties = {"ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>"}
 client = MongoClient(
-   "mongodb://<hostname>:<port>",
+   "mongodb[+srv]://<hostname>:<port>",
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=properties
 )

source/includes/authentication/percent-encoding.rst

@@ -0,0 +1,10 @@
+.. important:: Percent-Encoding
+
+   You must :wikipedia:`percent-encode <Percent-encoding>` a username and password before
+   you include them in a MongoDB URI. The ``quote_plus()`` method, available in the 
+   `urllib.parse <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote_plus>`__
+   module, is one way to perform this task. For example, calling ``quote_plus("and / or")``
+   returns the string ``and+%2F+or``.
+
+   Don't percent-encode the username or password when passing them as arguments to
+   ``MongoClient``.

source/security.txt

@@ -23,7 +23,6 @@ Secure Your Data
    :maxdepth: 1
 
    Authentication </security/authentication>
-   Enterprise Authentication </security/enterprise-authentication>
    In-Use Encryption </security/in-use-encryption>
 
 Overview