example fixes

mongoKart · mongoKart · commit 8a2b956c9f63 · 2025-01-22T12:49:38.000-06:00
diff --git a/source/includes/authentication/azure-envs-mongoclient.py b/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
 )
diff --git a/source/includes/authentication/azure-imds-connection-string.py b/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)
diff --git a/source/includes/authentication/azure-imds-mongoclient.py b/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
 )
diff --git a/source/includes/authentication/gcp-gke-mongoclient.py b/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
 )
diff --git a/source/includes/authentication/gcp-imds-connection-string.py b/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)
diff --git a/source/includes/authentication/gcp-imds-mongoclient.py b/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
 )
diff --git a/source/includes/authentication/percent-encoding.rst b/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``.
diff --git a/source/security.txt b/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
diff --git a/source/security/authentication.txt b/source/security/authentication.txt
@@ -1,4 +1,6 @@
 .. _pymongo-authentication-mechanisms:
+.. _pymongo-auth:
+.. _pymongo-enterprise-auth:
 
 =========================
 Authentication Mechanisms
@@ -37,7 +39,7 @@ the identity of a client to ensure security before connecting.
 
 .. tip:: Connecting to MongoDB
    
-   To learn how to establish a connection to your MongoDB deployment, see the
+   To learn how to establish a connection to your MongoDB deployment, see
    :ref:`pymongo-get-started`.
 
 MongoDB Edition Compatibility
diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt
@@ -36,12 +36,14 @@ Code Placeholders
 The code examples on this page use the following placeholders:
 
 - ``<hostname>``: The network address of your MongoDB Atlas deployment
-- ``<awsKeyId>``: Your AWS access key ID
-- ``<awsSecretKey>``: Your AWS secret access key
-- ``<awsSessionToken>``: Your AWS session token
+- ``<AWS IAM access key ID>``: Your AWS access key ID
+- ``<AWS IAM secret access key>``: Your AWS secret access key
+- ``<AWS session token>``: Your AWS session token
 
 To use the code examples on this page, replace these placeholders with your own values.
 
+.. include:: /includes/authentication/percent-encoding.rst
+
 Using AWS IAM Authentication in Your Application
 ------------------------------------------------
 
@@ -56,7 +58,7 @@ To use AWS IAM authentication, you must install {+driver-short+} with the
 tries to retrieve AWS credentials from the following sources, in the order listed:
 
 1. Named arguments passed to the ``MongoClient`` constructor or parameters in the
-   connection URI
+   connection string
 #. Environment variables
 #. Shared credentials file
 #. AWS config file
@@ -74,13 +76,13 @@ these sources and use them to authenticate your application.
 
 First, {+driver-short+} checks whether you passed AWS credentials
 to the ``MongoClient`` constructor, either as a named argument or as part of the
-connection URI. To pass your credentials to ``MongoClient``,
+connection string. To pass your credentials to ``MongoClient``,
 set the following connection options:
 
 - ``username``: The AWS IAM access key ID to authenticate. Percent-encode this value
-  before including it in a connection URI.
+  before including it in a connection string.
 - ``password``: The AWS IAM secret access key. Percent-encode this value before including
-  it in a connection URI.
+  it in a connection string.
 - ``authMechanism``: Set to ``"MONGODB-AWS"``.
 
 You can set these options in two ways: by passing arguments to the
@@ -93,7 +95,7 @@ You can set these options in two ways: by passing arguments to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://@<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       username="<AWS IAM access key ID>",
                                       password="<AWS IAM secret access key>",
                                       authMechanism="MONGODB-AWS")
@@ -103,9 +105,9 @@ You can set these options in two ways: by passing arguments to the
 
       .. code-block:: python
 
-         uri = ("mongodb://<percent-encoded AWS IAM access key ID>:"
+         uri = ("mongodb+srv://<percent-encoded AWS IAM access key ID>:"
                 "<percent-encoded AWS IAM secret access key>"
-                "@<hostname>:<port>/?"
+                "@<hostname>/?"
                 "&authMechanism=MONGODB-AWS")
          client = pymongo.MongoClient(uri)
 
@@ -148,15 +150,15 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       authMechanism="MONGODB-AWS")
 
    .. tab:: Connection String
       :tabid: connectionstring
 
       .. code-block:: python
 
-         uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
+         uri = "mongodb+srv://<hostname>/?&authMechanism=MONGODB-AWS"
          client = pymongo.MongoClient(uri)
 
 .. tip:: AWS Lambda
@@ -194,15 +196,15 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       authMechanism="MONGODB-AWS")
 
    .. tab:: Connection String
       :tabid: connectionstring
 
       .. code-block:: python
 
-         uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
+         uri = "mongodb+srv://<hostname>/?&authMechanism=MONGODB-AWS"
          client = pymongo.MongoClient(uri)
 
 .. tip::
@@ -244,15 +246,15 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       authMechanism="MONGODB-AWS")
 
    .. tab:: Connection String
       :tabid: connectionstring
 
       .. code-block:: python
 
-         uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
+         uri = "mongodb+srv://<hostname>/?&authMechanism=MONGODB-AWS"
          client = pymongo.MongoClient(uri)
 
 .. _pymongo-mongodb-aws-assume-role:
@@ -275,11 +277,11 @@ in the AWS documentation.
 After you create the config file, set the following connection options:
 
 - ``username``: The AWS IAM access key ID to authenticate returned by the ``AssumeRole``
-  request. Percent-encode this value before including it in a connection URI.
+  request. Percent-encode this value before including it in a connection string.
 - ``password``: The AWS IAM secret access key returned by the ``AssumeRole`` request.
-  Percent-encode this value before including it in a connection URI..
+  Percent-encode this value before including it in a connection string.
 - ``authMechanismProperties``: Set to ``AWS_SESSION_TOKEN:`` and the
-  AWS session token returned by the ``AssumeRole`` request. 
+  AWS session token returned by the ``AssumeRole`` request.
 - ``authMechanism``: Set to ``"MONGODB-AWS"``.
 
 You can set these options in two ways: by passing arguments to the
@@ -294,7 +296,7 @@ You can set these options in two ways: by passing arguments to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://@<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://@<hostname>",
                                       username="<AWS IAM access key ID>",
                                       password="<AWS IAM secret access key>",
                                       authMechanismProperties="AWS_SESSION_TOKEN:<AWS session token>",
@@ -305,9 +307,9 @@ You can set these options in two ways: by passing arguments to the
 
       .. code-block:: python
 
-         uri = ("mongodb://<percent-encoded AWS IAM access key ID>:"
+         uri = ("mongodb+srv://<percent-encoded AWS IAM access key ID>:"
                 "<percent-encoded AWS IAM secret access key>"
-                "@<hostname>:<port>/?"
+                "@<hostname>/?"
                 "authMechanismProperties=AWS_SESSION_TOKEN:<AWS session token>"
                 "&authMechanism=MONGODB-AWS")
          client = pymongo.MongoClient(uri)
@@ -353,15 +355,15 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       authMechanism="MONGODB-AWS")
 
    .. tab:: Connection String
       :tabid: connectionstring
 
       .. code-block:: python
 
-         uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
+         uri = "mongodb+srv://<hostname>/?&authMechanism=MONGODB-AWS"
          client = pymongo.MongoClient(uri)
 
 For more information about using an ``AssumeRoleWithWebIdentity`` request to
@@ -391,15 +393,15 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
+         client = pymongo.MongoClient("mongodb+srv://<hostname>",
                                       authMechanism="MONGODB-AWS")
 
    .. tab:: Connection String
       :tabid: connectionstring
 
       .. code-block:: python
 
-         uri = "mongodb://<hostname>:<port>/?&authMechanism=MONGODB-AWS"
+         uri = "mongodb+srv://<hostname>/?&authMechanism=MONGODB-AWS"
          client = pymongo.MongoClient(uri)
 
 API Documentation
diff --git a/source/security/authentication/kerberos.txt b/source/security/authentication/kerberos.txt
@@ -38,6 +38,8 @@ The code examples on this page use the following placeholders:
 
 To use the code examples on this page, replace these placeholders with your own values.
 
+.. include:: /includes/authentication/percent-encoding.rst
+
 Using GSSAPI Authentication in Your Application
 -----------------------------------------------
 
diff --git a/source/security/authentication/ldap.txt b/source/security/authentication/ldap.txt
@@ -1,9 +1,9 @@
 .. _pymongo-ldap:
 .. _pymongo-sasl:
 
-====
-LDAP
-====
+=================
+LDAP (PLAIN SASL)
+=================
 
 .. contents:: On this page
    :local:
@@ -26,7 +26,8 @@ Protocol (LDAP) username and password to authenticate to MongoDB.
 LDAP authentication uses the PLAIN Simple Authentication and Security Layer
 (SASL) defined in `RFC-4616 <https://tools.ietf.org/html/rfc4616>`__.
 
-You can use this mechanism only when authenticating to MongoDB Enterprise Advanced.
+You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB Enterprise
+Advanced.
 
 .. important::
 
@@ -40,17 +41,23 @@ Code Placeholders
 
 The code examples on this page use the following placeholders:
 
+- ``+srv``: Include this option in your connection string prefix only if you are connecting
+  to a MongoDB Atlas cluster. To learn more about the ``+srv`` option, see
+  :manual:`Connection String Formats </reference/connection-string/#connection-string-formats>`
+  in the {+mdb-server+} manual.
 - ``<username>``: Your LDAP username.
 - ``<password>``: Your LDAP password.
 - ``<hostname>``: The network address of your MongoDB deployment.
 - ``<port>``: The port number of your MongoDB deployment. If you omit this parameter,
   the driver uses the default port number (``27017``). You don't need to specify a port
   when connecting to a MongoDB Atlas cluster.
 - ``<authenticationDb>``: The MongoDB database that contains the user's LDAP credentials.
-   If you omit this parameter, the driver uses the default database (``admin``).
+  If you omit this parameter, the driver uses the default database (``admin``).
 
 To use the code examples on this page, replace these placeholders with your own values.
 
+.. include:: /includes/authentication/percent-encoding.rst
+
 Using PLAIN Authentication in Your Application
 ----------------------------------------------
 
@@ -67,9 +74,10 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         client = pymongo.MongoClient("mongodb://<hostname>:<port>",
-                                      username="<db_username>",
-                                      password="<db_password>",
+         client = pymongo.MongoClient("mongodb[+srv]://<hostname>:<port>",
+                                      username="<username>",
+                                      password="<password>",
+                                      authSource="<authenticationDb>",
                                       authMechanism="PLAIN",
                                       tls=True)
 
@@ -78,7 +86,8 @@ You can set this option in two ways: by passing an argument to the
 
       .. code-block:: python
 
-         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+         uri = ("mongodb[+srv]://<username>:<password>@<hostname>:<port>/?"
+                "authSource=<authenticationDb>"
                 "&authMechanism=PLAIN"
                 "&tls=true")
          client = pymongo.MongoClient(uri)
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

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:`
`9`	`9`	`return OIDCCallbackResult(access_token=token)`
`10`	`10`	`properties = {"OIDC_CALLBACK": MyCallback()}`
`11`	`11`	`client = MongoClient(`
`12`		`- "mongodb://<hostname>:<port>",`
	`12`	`+ "mongodb[+srv]://<hostname>:<port>",`
`13`	`13`	`authMechanism="MONGODB-OIDC",`
`14`	`14`	`authMechanismProperties=properties`
`15`	`15`	`)`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`# define properties and MongoClient`
`4`	`4`	`properties = {"ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>"}`
`5`	`5`	`client = MongoClient(`
`6`		`- "mongodb://<hostname>:<port>",`
	`6`	`+ "mongodb[+srv]://<hostname>:<port>",`
`7`	`7`	`authMechanism="MONGODB-OIDC",`
`8`	`8`	`authMechanismProperties=properties`
`9`	`9`	`)`