Skip to content

Commit ec1dac5

Browse files
eramongodberamongodb
authored
CDRIVER-4489 update URI documentation for authMechanismProperties (#1941)
* CDRIVER-5933 deprecate GSSAPI URI options
1 parent b1ff5d6 commit ec1dac5

File tree

3 files changed

+89
-18
lines changed

3 files changed

+89
-18
lines changed

‎src/libmongoc/doc/mongoc_uri_t.rst

Lines changed: 55 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -122,20 +122,67 @@ Authentication Options
122122
Constant Key Description
123123
========================================== ================================= =========================================================================================================================================================================================================================
124124
MONGOC_URI_AUTHMECHANISM authmechanism Specifies the mechanism to use when authenticating as the provided user. See `Authentication <authentication_>`_ for supported values.
125-
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.
126-
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.
125+
MONGOC_URI_AUTHMECHANISMPROPERTIES authmechanismproperties Additional properties for the specified mechanism using key-value pair format, e.g. ``key1:value1,key2:value2``.
126+
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.
127127
========================================== ================================= =========================================================================================================================================================================================================================
128128

129+
.. _authentication_mechanism_properties:
130+
129131
Mechanism Properties
130132
~~~~~~~~~~~~~~~~~~~~
131133

132-
========================================== ================================= =========================================================================================================================================================================================================================
133-
Constant Key Description
134-
========================================== ================================= =========================================================================================================================================================================================================================
135-
MONGOC_URI_CANONICALIZEHOSTNAME canonicalizehostname Use the canonical hostname of the service, rather than its configured alias, when authenticating with Cyrus-SASL Kerberos.
136-
MONGOC_URI_GSSAPISERVICENAME gssapiservicename Use alternative service name. The default is ``mongodb``.
137-
========================================== ================================= =========================================================================================================================================================================================================================
134+
The following properties may be specified as key-value pairs for the ``MONGOC_URI_AUTHMECHANISMPROPERTIES`` option.
135+
136+
These properties may only be specified when the corresponding authentication mechanism is also specified.
137+
138+
MONGODB-OIDC
139+
^^^^^^^^^^^^
140+
141+
============== =========================================================================================
142+
Key Value
143+
============== =========================================================================================
144+
ENVIRONMENT The name of a built-in OIDC provider integration. Must be one of ["azure", "gcp", "k8s"].
145+
TOKEN_RESOURCE The URI of the target resource. ``ENVIRONMENT`` must be one of ["azure", "gcp"].
146+
============== =========================================================================================
147+
148+
.. warning::
149+
150+
The value of the ``TOKEN_RESOURCE`` property MUST NOT contain the comma character "," when specified as a connection string query option.
151+
Any commas in the value MUST be percent-encoded (as "%2C") to avoid being interpreted as a key-value pair delimiter.
152+
However, the value MAY contain the colon character ":", as only the first colon is interpreted as a key-value delimiter.
153+
154+
GSSAPI
155+
^^^^^^
156+
157+
====================== ===================================================================================================================================================================================================================================
158+
Key Value
159+
====================== ===================================================================================================================================================================================================================================
160+
SERVICE_NAME Optional. Defaults to "mongodb".
161+
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").
162+
SERVICE_REALM Optional. May be needed for cross-realm authentication where the user and service exist in different realms.
163+
SERVICE_HOST Optional. May be needed to use a service host that differs from the initial role.
164+
====================== ===================================================================================================================================================================================================================================
165+
166+
MONGODB-AWS
167+
^^^^^^^^^^^
168+
169+
================= ====================================================================================
170+
Key Value
171+
================= ====================================================================================
172+
AWS_SESSION_TOKEN Optional. An AWS session token to use for authentication with temporary credentials.
173+
================= ====================================================================================
174+
175+
Deprecated Mechanism Property Options
176+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
177+
178+
The following options have been deprecated and may be removed from future releases of libmongoc.
138179

180+
========================================== ================================= ==================================================================== =======================
181+
Constant Key Deprecated For Key
182+
========================================== ================================= ==================================================================== =======================
183+
MONGOC_URI_CANONICALIZEHOSTNAME canonicalizehostname MONGOC_URI_AUTHMECHANISMPROPERTIES (CANONICALIZE_HOST_NAME) authmechanismproperties
184+
MONGOC_URI_GSSAPISERVICENAME gssapiservicename MONGOC_URI_AUTHMECHANISMPROPERTIES (SERVICE_NAME) authmechanismproperties
185+
========================================== ================================= ==================================================================== =======================
139186

140187
.. _tls_options:
141188

‎src/libmongoc/src/mongoc/mongoc-uri.c

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -733,11 +733,18 @@ mongoc_uri_option_is_int64 (const char *key)
733733
bool
734734
mongoc_uri_option_is_bool (const char *key)
735735
{
736-
return !strcasecmp (key, MONGOC_URI_CANONICALIZEHOSTNAME) || !strcasecmp (key, MONGOC_URI_DIRECTCONNECTION) ||
737-
!strcasecmp (key, MONGOC_URI_JOURNAL) || !strcasecmp (key, MONGOC_URI_RETRYREADS) ||
738-
!strcasecmp (key, MONGOC_URI_RETRYWRITES) || !strcasecmp (key, MONGOC_URI_SAFE) ||
739-
!strcasecmp (key, MONGOC_URI_SERVERSELECTIONTRYONCE) || !strcasecmp (key, MONGOC_URI_TLS) ||
740-
!strcasecmp (key, MONGOC_URI_TLSINSECURE) || !strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDCERTIFICATES) ||
736+
// CDRIVER-5933
737+
if (!strcasecmp (key, MONGOC_URI_CANONICALIZEHOSTNAME)) {
738+
MONGOC_WARNING (MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
739+
" with CANONICALIZE_HOST_NAME instead");
740+
return true;
741+
}
742+
743+
return !strcasecmp (key, MONGOC_URI_DIRECTCONNECTION) || !strcasecmp (key, MONGOC_URI_JOURNAL) ||
744+
!strcasecmp (key, MONGOC_URI_RETRYREADS) || !strcasecmp (key, MONGOC_URI_RETRYWRITES) ||
745+
!strcasecmp (key, MONGOC_URI_SAFE) || !strcasecmp (key, MONGOC_URI_SERVERSELECTIONTRYONCE) ||
746+
!strcasecmp (key, MONGOC_URI_TLS) || !strcasecmp (key, MONGOC_URI_TLSINSECURE) ||
747+
!strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDCERTIFICATES) ||
741748
!strcasecmp (key, MONGOC_URI_TLSALLOWINVALIDHOSTNAMES) ||
742749
!strcasecmp (key, MONGOC_URI_TLSDISABLECERTIFICATEREVOCATIONCHECK) ||
743750
!strcasecmp (key, MONGOC_URI_TLSDISABLEOCSPENDPOINTCHECK) || !strcasecmp (key, MONGOC_URI_LOADBALANCED) ||
@@ -1117,9 +1124,15 @@ mongoc_uri_apply_options (mongoc_uri_t *uri, const bson_t *options, bool from_dn
11171124
MONGOC_WARNING ("authMechanismProperties SERVICE_NAME already set, "
11181125
"ignoring '%s'",
11191126
key);
1120-
} else if (!mongoc_uri_parse_auth_mechanism_properties (uri, tmp)) {
1121-
bson_free (tmp);
1122-
goto UNSUPPORTED_VALUE;
1127+
} else {
1128+
// CDRIVER-5933
1129+
MONGOC_WARNING (MONGOC_URI_GSSAPISERVICENAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
1130+
" with SERVICE_NAME instead");
1131+
1132+
if (!mongoc_uri_parse_auth_mechanism_properties (uri, tmp)) {
1133+
bson_free (tmp);
1134+
goto UNSUPPORTED_VALUE;
1135+
}
11231136
}
11241137
bson_free (tmp);
11251138

‎src/libmongoc/tests/test-mongoc-uri.c

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1362,11 +1362,15 @@ test_mongoc_uri_functions (void)
13621362
ASSERT_CMPSTR (mongoc_uri_get_auth_source (client->uri), "longer authsource that should work");
13631363
mongoc_client_destroy (client);
13641364

1365-
1365+
capture_logs (true);
13661366
uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_SERVERSELECTIONTIMEOUTMS "=3"
13671367
"&" MONGOC_URI_JOURNAL "=true"
13681368
"&" MONGOC_URI_WTIMEOUTMS "=42"
13691369
"&" MONGOC_URI_CANONICALIZEHOSTNAME "=false");
1370+
ASSERT_CAPTURED_LOG ("mongoc_uri_new",
1371+
MONGOC_LOG_LEVEL_WARNING,
1372+
MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
1373+
" with CANONICALIZE_HOST_NAME instead");
13701374

13711375
ASSERT_CMPINT (mongoc_uri_get_option_as_int32 (uri, "serverselectiontimeoutms", 18), ==, 3);
13721376
ASSERT (mongoc_uri_set_option_as_int32 (uri, "serverselectiontimeoutms", 18));
@@ -1410,7 +1414,6 @@ test_mongoc_uri_functions (void)
14101414
mongoc_uri_destroy (uri);
14111415

14121416
ASSERT (mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_JOURNAL, false));
1413-
ASSERT (!mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_CANONICALIZEHOSTNAME, true));
14141417
/* tls isn't set, return out fallback */
14151418
ASSERT (mongoc_uri_get_option_as_bool (client->uri, MONGOC_URI_TLS, true));
14161419
mongoc_client_destroy (client);
@@ -2932,6 +2935,10 @@ test_mongoc_uri_duplicates (void)
29322935
ASSERT_CMPSTR (str, "b");
29332936

29342937
RECREATE_URI (MONGOC_URI_CANONICALIZEHOSTNAME "=false&" MONGOC_URI_CANONICALIZEHOSTNAME "=true");
2938+
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_CANONICALIZEHOSTNAME,
2939+
MONGOC_LOG_LEVEL_WARNING,
2940+
MONGOC_URI_CANONICALIZEHOSTNAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
2941+
" with CANONICALIZE_HOST_NAME instead");
29352942
ASSERT_LOG_DUPE (MONGOC_URI_CANONICALIZEHOSTNAME);
29362943
ASSERT (mongoc_uri_get_option_as_bool (uri, MONGOC_URI_CANONICALIZEHOSTNAME, false));
29372944

@@ -2948,6 +2955,10 @@ test_mongoc_uri_duplicates (void)
29482955

29492956
RECREATE_URI (MONGOC_URI_AUTHMECHANISM "=GSSAPI&" MONGOC_URI_GSSAPISERVICENAME "=a&" MONGOC_URI_GSSAPISERVICENAME
29502957
"=b");
2958+
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_GSSAPISERVICENAME,
2959+
MONGOC_LOG_LEVEL_WARNING,
2960+
MONGOC_URI_GSSAPISERVICENAME " is deprecated, use " MONGOC_URI_AUTHMECHANISMPROPERTIES
2961+
" with SERVICE_NAME instead");
29512962
ASSERT_CAPTURED_LOG ("option: " MONGOC_URI_GSSAPISERVICENAME,
29522963
MONGOC_LOG_LEVEL_WARNING,
29532964
"Overwriting previously provided value for 'gssapiservicename'");

0 commit comments

Comments
 (0)