Skip to content

CDRIVER-4489 update URI documentation for authMechanismProperties #1941

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 20, 2025
Merged

CDRIVER-4489 update URI documentation for authMechanismProperties #1941

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee3513a
CDRIVER-5933 deprecate GSSAPI URI options
eramongodb Mar 19, 2025
34757bb
CDRIVER-4489 update URI documentation for authMechanismProperties
eramongodb Mar 19, 2025
da8101a
Fix documentation of AWS_SESSION_TOKEN
eramongodb Mar 20, 2025
2a06caf
CDRIVER-5933 emit warnings for deprecated GSSAPI URI options
eramongodb Mar 20, 2025
f648dfa
Fix branch conditions for gssapiservicename
eramongodb Mar 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 55 additions & 8 deletions src/libmongoc/doc/mongoc_uri_t.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,20 +122,67 @@ Authentication Options
Constant Key Description
========================================== ================================= =========================================================================================================================================================================================================================
MONGOC_URI_AUTHMECHANISM authmechanism Specifies the mechanism to use when authenticating as the provided user. See `Authentication <authentication_>`_ for supported values.
MONGOC_URI_AUTHMECHANISMPROPERTIES authmechanismproperties Certain authentication mechanisms have additional options that can be configured. These options should be provided as comma separated option_key:option_value pair and provided as authMechanismProperties. Specifying the same option_key multiple times has undefined behavior.
MONGOC_URI_AUTHSOURCE authsource The authSource defines the database that should be used to authenticate to. It is unnecessary to provide this option the database name is the same as the database used in the URI.
MONGOC_URI_AUTHMECHANISMPROPERTIES authmechanismproperties Additional properties for the specified mechanism using key-value pair format, e.g. ``key1:value1,key2:value2``.
MONGOC_URI_AUTHSOURCE authsource The name of the database to which authentication commands are sent or ``$external`` depending on the specified mechanism. Overrides the auth database in the URI when applicable.
========================================== ================================= =========================================================================================================================================================================================================================

.. _authentication_mechanism_properties:

Mechanism Properties
~~~~~~~~~~~~~~~~~~~~

========================================== ================================= =========================================================================================================================================================================================================================
Constant Key Description
========================================== ================================= =========================================================================================================================================================================================================================
MONGOC_URI_CANONICALIZEHOSTNAME canonicalizehostname Use the canonical hostname of the service, rather than its configured alias, when authenticating with Cyrus-SASL Kerberos.
MONGOC_URI_GSSAPISERVICENAME gssapiservicename Use alternative service name. The default is ``mongodb``.
========================================== ================================= =========================================================================================================================================================================================================================
The following properties may be specified as key-value pairs for the ``MONGOC_URI_AUTHMECHANISMPROPERTIES`` option.

These properties may only be specified when the corresponding authentication mechanism is also specified.

MONGODB-OIDC
^^^^^^^^^^^^

============== =========================================================================================
Key Value
============== =========================================================================================
ENVIRONMENT The name of a built-in OIDC provider integration. Must be one of ["azure", "gcp", "k8s"].
TOKEN_RESOURCE The URI of the target resource. ``ENVIRONMENT`` must be one of ["azure", "gcp"].
============== =========================================================================================

.. warning::

The value of the ``TOKEN_RESOURCE`` property MUST NOT contain the comma character "," when specified as a connection string query option.
Any commas in the value MUST be percent-encoded (as "%2C") to avoid being interpreted as a key-value pair delimiter.
However, the value MAY contain the colon character ":", as only the first colon is interpreted as a key-value delimiter.

GSSAPI
^^^^^^

====================== ===================================================================================================================================================================================================================================
Key Value
====================== ===================================================================================================================================================================================================================================
SERVICE_NAME Optional. Defaults to "mongodb".
CANONICALIZE_HOST_NAME Optional. Must be one of ["false", "true"]. "false" performs no canonicalization (aka "none"). "true" performs a forward DNS lookup and then a reverse lookup on that value to canonicalize the hostname (aka "forwardAndReverse").
SERVICE_REALM Optional. May be needed for cross-realm authentication where the user and service exist in different realms.
SERVICE_HOST Optional. May be needed to use a service host that differs from the initial role.
====================== ===================================================================================================================================================================================================================================

MONGODB-AWS
^^^^^^^^^^^

================= ====================================================================================
Key Value
================= ====================================================================================
AWS_SESSION_TOKEN Optional. An AWS session token to use for authentication with temporary credentials.
================= ====================================================================================

Deprecated Mechanism Property Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following options have been deprecated and may be removed from future releases of libmongoc.

========================================== ================================= ==================================================================== =======================
Constant Key Deprecated For Key
========================================== ================================= ==================================================================== =======================
MONGOC_URI_CANONICALIZEHOSTNAME canonicalizehostname MONGOC_URI_AUTHMECHANISMPROPERTIES (CANONICALIZE_HOST_NAME) authmechanismproperties
MONGOC_URI_GSSAPISERVICENAME gssapiservicename MONGOC_URI_AUTHMECHANISMPROPERTIES (SERVICE_NAME) authmechanismproperties
========================================== ================================= ==================================================================== =======================

.. _tls_options:

Expand Down
29 changes: 21 additions & 8 deletions src/libmongoc/src/mongoc/mongoc-uri.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -733,11 +733,18 @@ mongoc_uri_option_is_int64 (const char *key)
bool
mongoc_uri_option_is_bool (const char *key)
{
return !strcasecmp (key, MONGOC_URI_CANONICALIZEHOSTNAME) || !strcasecmp (key, MONGOC_URI_DIRECTCONNECTION) ||
!strcasecmp (key, MONGOC_URI_JOURNAL) || !strcasecmp (key, MONGOC_URI_RETRYREADS) ||
!strcasecmp (key, MONGOC_URI_RETRYWRITES) || !strcasecmp (key, MONGOC_URI_SAFE) ||
!strcasecmp (key, MONGOC_URI_SERVERSELECTIONTRYONCE) || !strcasecmp (key, MONGOC_URI_TLS) ||
!strcasecmp (key, MONGOC_URI_TLSINSECURE) || !strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDCERTIFICATES) ||
// CDRIVER-5933
if (!strcasecmp (key, MONGOC_URI_CANONICALIZEHOSTNAME)) {
MONGOC_WARNING (MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
" with CANONICALIZE_HOST_NAME instead");
return true;
}

return !strcasecmp (key, MONGOC_URI_DIRECTCONNECTION) || !strcasecmp (key, MONGOC_URI_JOURNAL) ||
!strcasecmp (key, MONGOC_URI_RETRYREADS) || !strcasecmp (key, MONGOC_URI_RETRYWRITES) ||
!strcasecmp (key, MONGOC_URI_SAFE) || !strcasecmp (key, MONGOC_URI_SERVERSELECTIONTRYONCE) ||
!strcasecmp (key, MONGOC_URI_TLS) || !strcasecmp (key, MONGOC_URI_TLSINSECURE) ||
!strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDCERTIFICATES) ||
!strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDHOSTNAMES) ||
!strcasecmp (key, MONGOC_URI_TLSDISABLECERTIFICATEREVOCATIONCHECK) ||
!strcasecmp (key, MONGOC_URI_TLSDISABLEOCSPENDPOINTCHECK) || !strcasecmp (key, MONGOC_URI_LOADBALANCED) ||
Expand Down Expand Up @@ -1117,9 +1124,15 @@ mongoc_uri_apply_options (mongoc_uri_t *uri, const bson_t *options, bool from_dn
MONGOC_WARNING ("authMechanismProperties SERVICE_NAME already set, "
"ignoring '%s'",
key);
} else if (!mongoc_uri_parse_auth_mechanism_properties (uri, tmp)) {
bson_free (tmp);
goto UNSUPPORTED_VALUE;
} else {
// CDRIVER-5933
MONGOC_WARNING (MONGOC_URI_GSSAPISERVICENAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
" with SERVICE_NAME instead");

if (!mongoc_uri_parse_auth_mechanism_properties (uri, tmp)) {
bson_free (tmp);
goto UNSUPPORTED_VALUE;
}
}
bson_free (tmp);

Expand Down
15 changes: 13 additions & 2 deletions src/libmongoc/tests/test-mongoc-uri.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1367,11 +1367,15 @@ test_mongoc_uri_functions (void)
ASSERT_CMPSTR (mongoc_uri_get_auth_source (client->uri), "longer authsource that should work");
mongoc_client_destroy (client);


capture_logs (true);
uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_SERVERSELECTIONTIMEOUTMS "=3"
"&" MONGOC_URI_JOURNAL "=true"
"&" MONGOC_URI_WTIMEOUTMS "=42"
"&" MONGOC_URI_CANONICALIZEHOSTNAME "=false");
ASSERT_CAPTURED_LOG ("mongoc_uri_new",
MONGOC_LOG_LEVEL_WARNING,
MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
" with CANONICALIZE_HOST_NAME instead");

ASSERT_CMPINT (mongoc_uri_get_option_as_int32 (uri, "serverselectiontimeoutms", 18), ==, 3);
ASSERT (mongoc_uri_set_option_as_int32 (uri, "serverselectiontimeoutms", 18));
Expand Down Expand Up @@ -1415,7 +1419,6 @@ test_mongoc_uri_functions (void)
mongoc_uri_destroy (uri);

ASSERT (mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_JOURNAL, false));
ASSERT (!mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_CANONICALIZEHOSTNAME, true));
/* tls isn't set, return out fallback */
ASSERT (mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_TLS, true));
mongoc_client_destroy (client);
Expand Down Expand Up @@ -2937,6 +2940,10 @@ test_mongoc_uri_duplicates (void)
ASSERT_CMPSTR (str, "b");

RECREATE_URI (MONGOC_URI_CANONICALIZEHOSTNAME "=false&" MONGOC_URI_CANONICALIZEHOSTNAME "=true");
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_CANONICALIZEHOSTNAME,
MONGOC_LOG_LEVEL_WARNING,
MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
" with CANONICALIZE_HOST_NAME instead");
ASSERT_LOG_DUPE (MONGOC_URI_CANONICALIZEHOSTNAME);
ASSERT (mongoc_uri_get_option_as_bool (uri, MONGOC_URI_CANONICALIZEHOSTNAME, false));

Expand All @@ -2953,6 +2960,10 @@ test_mongoc_uri_duplicates (void)

RECREATE_URI (MONGOC_URI_AUTHMECHANISM "=GSSAPI&" MONGOC_URI_GSSAPISERVICENAME "=a&" MONGOC_URI_GSSAPISERVICENAME
"=b");
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_GSSAPISERVICENAME,
MONGOC_LOG_LEVEL_WARNING,
MONGOC_URI_GSSAPISERVICENAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
" with SERVICE_NAME instead");
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_GSSAPISERVICENAME,
MONGOC_LOG_LEVEL_WARNING,
"Overwriting previously provided value for 'gssapiservicename'");
Expand Down