DRIVERS-2769 Clarify not validating saslSupportedMechs (#1565)

Author: comandeo-mongo

source/auth/auth.md

@@ -174,6 +174,9 @@ If the handshake response includes a `saslSupportedMechs` field, then drivers MU
 select a default mechanism as described later. If the command succeeds and the response does not include a
 `saslSupportedMechs` field, then drivers MUST use the legacy default mechanism rules for servers older than 4.0.
 
+Drivers MUST NOT validate the contents of the `saslSupportedMechs` attribute of the initial handshake reply. Drivers
+MUST NOT raise an error if the `saslSupportedMechs` attribute of the reply includes an unknown mechanism.
+
 ### Single-credential drivers
 
 When the authentication mechanism is not specified, drivers that allow only a single credential per client MUST perform
@@ -2050,6 +2053,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 2024-04-22: Clarify that driver should not validate `saslSupportedMechs` content.
+
 - 2024-04-03: Added GCP built-in OIDC provider integration.
 
 - 2024-03-29: Updated OIDC test setup and descriptions.

source/auth/auth.rst

@@ -217,6 +217,11 @@ to select a default mechanism as described later.  If the command succeeds and
 the response does not include a ``saslSupportedMechs`` field, then drivers MUST
 use the legacy default mechanism rules for servers older than 4.0.
 
+Drivers MUST NOT validate the contents of the ``saslSupportedMechs``
+attribute of the initial handshake reply. Drivers MUST NOT raise an error if
+the ``saslSupportedMechs`` attribute of the reply includes an unknown mechanism.
+
+
 Single-credential drivers
 `````````````````````````
 
@@ -1661,6 +1666,7 @@ Q: Should drivers support accessing Amazon EC2 instance metadata in Amazon ECS?
 Changelog
 =========
 
+:2024-04-22: Clarify that driver should not validate ``saslSupportedMechs`` content.
 :2023-04-28: Added MONGODB-OIDC auth mechanism
 :2022-11-02: Require environment variables to be read dynamically.
 :2022-10-28: Recommend the use of AWS SDKs where available.

source/mongodb-handshake/handshake.rst

@@ -424,6 +424,10 @@ The ``speculativeAuthenticate`` reply has the same fields, except for the ``ok``
 as seen in the conversation sections for MONGODB-X509, SCRAM-SHA-1 and SCRAM-SHA-256
 in the `Driver Authentication spec <../auth/auth.md#supported-authentication-methods>`_.
 
+Drivers MUST NOT validate the contents of the ``saslSupportedMechs`` attribute
+of the initial handshake reply. Drivers MUST NOT raise an error if the
+``saslSupportedMechs`` attribute of the reply includes an unknown mechanism.
+
 If an authentication mechanism is not provided either via connection string or code, but
 a credential is provided, drivers MUST use the SCRAM-SHA-256 mechanism for speculative
 authentication and drivers MUST send ``saslSupportedMechs``.
@@ -675,3 +679,4 @@ Changelog
 :2023-04-03: Simplify truncation for metadata
 :2023-05-04: ``AWS_EXECUTION_ENV`` must start with ``"AWS_Lambda_"``
 :2023-08-24: Added container awareness
+:2024-04-22: Clarify that driver should not validate ``saslSupportedMechs`` content.

source/mongodb-handshake/tests/README.md

@@ -0,0 +1,12 @@
+# MongoDB Handshake Tests
+
+## Prose Tests
+
+### Test that the driver accepts an arbitrary auth mechanism
+
+1. Mock the server response in a way that `saslSupportedMechs` array in the `hello` command response contains an
+   arbitrary string.
+
+2. Create and connect a `Connection` object that connects to the server that returns the mocked response.
+
+3. Assert that no error is raised.