[DOCS-9897] Document authMechanismProperties URI option and deprecate gssapiServiceName Created: 15/Feb/17  Updated: 30/Oct/23  Due: 09/Feb/18  Resolved: 05/Dec/18

Status: Closed
Project: Documentation
Component/s: manual
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Task Priority: Major - P3
Reporter: Jeremy Mikola Assignee: Ravind Kumar (Inactive)
Resolution: Done Votes: 4
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to PHPC-915 Document precedence of authMechanismP... Closed
is related to NODE-1651 Kerberos Service Name Never Anything ... Closed
Participants:
Days since reply: 5 years, 10 weeks ago
Story Points: 0.1

 Description   

The authentication spec defines a authMechanismProperties option and lists gssapiServiceName as a deprecated alias for "authMechanismProperties=SERVICE_NAME:mongodb". At present, authMechanismProperties are only supported for the GSSAPI authMechanism. There are three documented authMechanismProperties; however, not all properties are supported by all drivers. "SERVICE_NAME" should exist in any driver, as it is a "MUST" according to the specification.

The addition of both options is discussed in the spec's version history, although that history has been in place since the spec was first publicized in f53b992. I don't have exact dates for these changes, but authMechanismProperties dates back to 2014 in JAVA-1466. If authMechanismProperties was introduced in conjunction with SCRAM-SHA-1, it's possible that this dates back to MongoDB 3.0.

 

Scope

Update authentication options table to include authMechanismProperties and it's supported properties:

SERVICE_NAME
   Drivers MUST allow the user to specify a different service name. The default is "mongodb".
 
CANONICALIZE_HOST_NAME
   Drivers MAY allow the user to request canonicalization of the hostname. This might be required
   when the hosts report different hostnames than what is used in the kerberos database. The 
   default is "false".
SERVICE_REALM
  Drivers MAY allow the user to specify a different realm for the service. This might be 
  necessary to support cross-realm authentication where the user exists in one realm and the 
  service in another. 

 

Note that authMechanismProperites apply only when authMechanism is  GSSAPI

Update gssapiServiceName to note that it's an alias for authMechanismProperties=SERVICE_NAME:mongodb



 Comments   
Comment by Ravind Kumar (Inactive) [ 05/Dec/18 ]

published to https://docs.mongodb.com/master/reference/connection-string/#urioption.authMechanismProperties, older versions to follow

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: Additional fix
Branch: v3.4
https://github.com/mongodb/docs/commit/dd3c12469f487e1a0046de78a6b60932711cffb6

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: Additional fix
Branch: v3.6
https://github.com/mongodb/docs/commit/4ce49cf818aca8bec2e9309246604eae4df8c933

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: Additional fix
Branch: v4.0
https://github.com/mongodb/docs/commit/fb34441d097237e8bfcc21dac34fba0a71d88d04

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: Additional fix
Branch: master
https://github.com/mongodb/docs/commit/e4df19c1c6db63ddd52b0969e08e9b295f6a38a1

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: Typo from DOCS-9897
Branch: master
https://github.com/mongodb/docs/commit/0f4ad4d9916049733a8050db1e6c63c76687843e

Comment by Ravind Kumar (Inactive) [ 05/Dec/18 ]

Changes are merged into master (4.2), 4.0, 3.6, and 3.4. They should be visible after our next publishing (EOD).

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: authMechanismProperties for URI connection string
Branch: v3.4
https://github.com/mongodb/docs/commit/b73ab6694de5931d1deb7d87fcdf4a4edf7217e0

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: authMechanismProperties for URI connection string
Branch: v3.6
https://github.com/mongodb/docs/commit/20ce897ea154192332123cc9ad0b52ca959cd1ef

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: authMechanismProperties for URI connection string
Branch: v4.0
https://github.com/mongodb/docs/commit/18b9ff075b7fbe1d735ec265eac63e26e3939b2f

Comment by Githook User [ 05/Dec/18 ]

Author:

{'name': 'rkumar-mongo', 'email': 'ravind.kumar@mongodb.com'}

Message: DOCS-9897: authMechanismProperties for URI connection string
Branch: master
https://github.com/mongodb/docs/commit/39db3909d8616eb123220ac665d039ba6d7b3db1

Comment by Shane Harvey [ 19/Sep/18 ]

Thanks, Luke. In that case, perhaps we should wait until DRIVERS-557 is completed. That project might make it easier to write correct documentation on which URI options all drivers support.

Comment by Luke Prochazka [ 14/Aug/18 ]

I would like to see gssapiHostName represented in the authMechanismProperties as a supported option. Noting this is distinct from the CANONICALIZE_HOST_NAME and SERVICE_REALM options mentioned in the auth spec.

Comment by Shane Harvey [ 06/Feb/18 ]

Yes, that sounds correct to me.

Comment by Ravind Kumar (Inactive) [ 06/Feb/18 ]

shane.harvey am I right in thinking that we just need to remove (or mark as deprecated) the gssapiServiceName param and add authMechanismProperties, specifying the three possible values there. We can note that only SERVICE_NAME is supported by all drivers, and that the rest require users to check the driver docs for support.

Comment by Shane Harvey [ 06/Feb/18 ]

Can this ticket be scheduled? It's a relatively simple change to the connection string docs.

Comment by Jeremy Mikola [ 15/Feb/17 ]

Note that in libmongoc, authMechanismProperties takes precedence over both "gssapiServiceName" and
"canonicalizeHostname". The auth spec doesn't mention a "canonicalizeHostname" option, although the corresponding authMechanismProperties option is discussed.

The spec doesn't explicitly state that authMechanismProperties takes precedence, but I believe that may be implied by its deprecation of the "gssapiServiceName" option. If the manual will continue to document the "gssapiServiceName" option, I expect we'll want to clarify the precendence as well (and confirm that most drivers and the shell follow this convention).

Generated at Thu Feb 08 07:59:23 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.