DOCSP-24594-Compass-auth-examples #708

ltran-mdb2 · 2025-01-10T16:57:07Z

DESCRIPTION

Adds examples of Compass authentication

STAGING

https://deploy-preview-708--docs-compass.netlify.app/connect/advanced-connection-options/general-connection/#example
https://deploy-preview-708--docs-compass.netlify.app/connect/advanced-connection-options/authentication-connection/#examples
https://deploy-preview-708--docs-compass.netlify.app/connect/advanced-connection-options/tls-ssl-connection/#example
https://deploy-preview-708--docs-compass.netlify.app/connect/advanced-connection-options/advanced-connection/#example

JIRA

https://jira.mongodb.org/browse/DOCSP-24594

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Is this free of spelling errors?
Is this free of grammatical errors?
Is this free of staging / rendering issues?
Are all the links working?

External Review Requirements

What's expected of an external reviewer?

netlify · 2025-01-10T16:57:55Z

✅ Deploy Preview for docs-compass ready!

Name	Link
🔨 Latest commit	`4ae08c2`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-compass/deploys/6797f5c02b55690008c9be92
😎 Deploy Preview	https://deploy-preview-708--docs-compass.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jeff-allen-mongo

@ltran-mdb2 thanks for these updates. I think this is a good start and definitely in line with my initial suggestions. I left a few thoughts for your consideration. Feel free to reach out if you want to discuss anything.

Jeff

jeff-allen-mongo · 2025-01-13T16:32:12Z

source/connect/advanced-connection-options/advanced-connection.txt

@@ -78,6 +78,14 @@ Procedure
               read preference option. 
             - Any specified tag sets. 

+      The following screenshot shows the :guilabel:`Advanced`


I might consider moving these new examples under a dedicated "Example" heading after "Procedure". I feel like this might make them slightly easier to find, since they'd be clearly visible in the right-hand page ToC.

I was also thinking that another potential way to organize this content could be to create a new page under "Connect" called "Connection Examples" (or similar), and make these examples into distinct pages. As in the ToC would look something like:

| - Connect | - | - Connection Examples | - | - | - Connect to Atlas Deployment | - | - | - Connect to LDAP Deployment | - | - | - etc

This would be more work content-wise, but I'm wondering if it's worth having these examples on dedicated pages so they can be more easily found by users searching for phrases like "compass connect to Atlas" or "compass connect with LDAP".

I think it could also be fine to keep the structure largely as we have it now with the examples added to the existing pages, and consider a broader restructure in a future effort. Curious what you think.

I added an "Example" section for each page because I think it makes sense to keep the examples on the same pages as the procedures.

jeff-allen-mongo · 2025-01-13T16:47:25Z

source/connect/advanced-connection-options/advanced-connection.txt

+      tab configured with the read preference of :guilabel:`Secondary
+      Preferred`. 
+
+      .. figure:: /images/authentication/secondary-preferred.png


I'm curious for product / engineering's take here, but I'm wondering if in the examples we should be using the SRV Connection format. My understanding is that the SRV strings have the advantage of having TLS enabled by default, which might promote more secure practices. Not 100% sure about this though.

I changed the examples to use the srv connection format - @betsybutton what do you think?

Yes, +srv connection strings have TLS enabled by default, and we encourage users to use their connection strings when possible. Thanks for leaving this comment, Jeff!

jeff-allen-mongo · 2025-01-13T16:49:59Z

source/connect/advanced-connection-options/authentication-connection.txt

@@ -266,10 +266,19 @@ Procedure

      - (Optional) AWS Session Token

+      The following screenshot shows the :guilabel:`Authentication`


The example here feels slightly out of place to me. Since it immediately follows the AWS content, it seems like it should be showing an AWS example. Moving the examples to their own section (or page) as mentioned in my other comment might help.

jeff-allen-mongo · 2025-01-13T16:52:14Z

source/connect/advanced-connection-options/authentication-connection.txt

+      tab configured for username and password authentication with
+      SCRAM-SHA-256. 
+
+      .. figure:: /images/authentication/authentication-configuration.png


This is a bit of a nit, but I'm wondering if we should change the "Name" field in these example screenshots to be slightly more descriptive, rather than reusing the hostname and port. My concern is that users might think that their connection "Name" has to match the username and port, but it can be anything that helps identify the cluster.

jeff-allen-mongo · 2025-01-13T16:55:14Z

source/connect/advanced-connection-options/general-connection.txt

+
+                .. note::
+
+                   If you use the Standard Connection String Format to


[Nit]

I don't think "Standard Connection String Format" needs to be title case here.

jeff-allen-mongo · 2025-01-13T16:59:03Z

source/connect/advanced-connection-options/authentication-connection.txt

   .. step:: (Optional) For advanced connection configuration options, click the :ref:`Advanced <advanced-connection-tab>` tab.

   .. step:: Click Connect.

+


I think also including an LDAP example on this page would be helpful.

jeff-allen-mongo · 2025-01-13T17:01:40Z

source/connect/advanced-connection-options/advanced-connection.txt

@@ -78,6 +78,14 @@ Procedure
               read preference option. 
             - Any specified tag sets. 

+      The following screenshot shows the :guilabel:`Advanced`
+      tab configured with the read preference of :guilabel:`Secondary
+      Preferred`. 


It might help to add a bit of context here explaining why a user might want to use "secondary preferred".

ltran-mdb2 · 2025-01-14T16:35:32Z

Thanks for your feedback @jeff-allen-mongo ! Could you take another look when you get a chance?

jeff-allen-mongo

LGTM! Just have a couple optional suggestions. Thanks @ltran-mdb2

jeff-allen-mongo · 2025-01-14T19:32:44Z

source/connect/advanced-connection-options/advanced-connection.txt

+Example
+-------
+
+The following screenshot shows the :guilabel:`Advanced` tab configured


[Suggestion]

Maybe to tighten up the wording slightly:

The following example specifies a connection with a read preference of :guilabel:Secondary Preferred.

We could apply a similar wording to the other example lead-ins.

jeff-allen-mongo · 2025-01-14T19:57:49Z

source/connect/advanced-connection-options/authentication-connection.txt

@@ -273,3 +273,22 @@ Procedure
 .. seealso::

   To disconnect from your deployment, see :ref:`<disconnect-tab>`.
+
+Example


[Suggestion]

Maybe we can make this "Examples" and have subheadings for each example? As in:

Examples ------------ Username and Password Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (example 1) LDAP Authentication ~~~~~~~~~~~~~~~~~~~~ (example 2)

jeff-allen-mongo · 2025-01-14T20:02:50Z

source/connect/advanced-connection-options/general-connection.txt

+</core/security-scram/>`. Since the connection uses the ``mongodb+srv``
+connection string scheme, the connection automatically enables TLS/SSL. 
+
+.. figure:: /images/authentication/new-atlas-connection.png


I noticed the other figures specified a figwidth of 662px. Should we add that here as well?

Thanks for catching this! Done!

jeff-allen-mongo · 2025-01-15T16:28:33Z

source/connect/advanced-connection-options/authentication-connection.txt

+   :figwidth: 662px
+   :alt: Screenshot of Compass configured to authenticate with username and password
+
+LDAP Authentication


Sorry, I realized after I suggested that we add this example that LDAP is actually deprecated. I wonder if we should remove this or replace with a different auth example? Happy to defer to product for their opinion here.

@betsybutton Do you have thoughts here?

Even though LDAP is deprecated, this is an area that has caused a lot of pain in the past, so I think it's worth including here. Some larger customers take much longer to upgrade to the latest MongoDB version, and we might as well provide the assistance.

betsybutton

Thanks so much for taking this work on, Lauren! So far, these examples cover the following types of connections:

SCRAM-SHA-256
Secondary Preferred
Username & password
LDAP Authentication
TLS/SSL

What would you think of adding examples for the following, which are other areas users have struggled a lot with? If it would be better to handle some of these in a followup ticket, that's also fine.

Private endpoints
OIDC
x509
Analytics nodes

For private endpoint and OIDC, it might be helpful to link to other docs that could help users diagnose these types of problems. For example, https://www.mongodb.com/docs/atlas/troubleshoot-private-endpoints/#std-label-pl-troubleshooting and https://www.mongodb.com/docs/atlas/security-oidc/

betsybutton · 2025-01-17T18:09:27Z

source/connect/advanced-connection-options/authentication-connection.txt

+   :figwidth: 662px
+   :alt: Screenshot of Compass configured to authenticate with username and password
+
+LDAP Authentication


Even though LDAP is deprecated, this is an area that has caused a lot of pain in the past, so I think it's worth including here. Some larger customers take much longer to upgrade to the latest MongoDB version, and we might as well provide the assistance.

betsybutton · 2025-01-17T18:19:45Z

source/connect/advanced-connection-options/authentication-connection.txt

@@ -273,3 +273,28 @@ Procedure
 .. seealso::

   To disconnect from your deployment, see :ref:`<disconnect-tab>`.
+
+Examples


[q] Is there a reason to list these examples all the way at the bottom, instead of including them in the sections pertinent to each connection method above? And if it's truly better to have these at the bottom, can we link to them from above? I'm worried they won't be very visible down here since they're hidden & not linked.

I added a note in the username/password and ldap sections linking to the according examples. The reason they are at the bottom is to make a dedicated ToC item on this page with the examples (see this comment from Jeff)

Got it, thanks for adding the link!

betsybutton · 2025-01-17T18:37:34Z

source/connect/advanced-connection-options/tls-ssl-connection.txt

+The following example specifies a connection with TLS/SSL enabled in the
+:guilabel:`TLS / SSL` tab.
+
+.. figure:: /images/authentication/tls-ssl-configuration.png
+   :figwidth: 662px
+   :alt: Screenshot of Compass configured to connect to an example cluster with TLS/SSL


There isn't really a reason to explicitly enable TLS/SSL when using an srv connection string, since it's enabled by default, especially when tlsCertificateKeyFile isn't specified. Maybe we could turn this into an x509 example, where we need to supply the client certificate and key?

ltran-mdb2 · 2025-01-24T01:26:02Z

Thanks for your feedback @betsybutton ! Could you take another look at this PR when you get a chance?

I also implemented some feedback from Felicia on the general connection example (changing it to use the mongodb scheme) as well as adding notes on when TLS/SSL is required.

I opened DOCSP-46801 to address the other examples you mentioned!

betsybutton

1 nit pick, otherwise LGTM!

betsybutton · 2025-01-27T18:28:30Z

source/connect/advanced-connection-options/tls-ssl-connection.txt

+The following example specifies a connection with TLS/SSL enabled in the
+:guilabel:`TLS / SSL` tab. This connection uses :manual:`X.509
+</core/security-x.509/>` authentication which requires a client
+certificate. 


The screenshot doesn't showcase selecting a .pem file right now - could we update it to mirror what a successful x509 setup would look like?

betsybutton

LGTM, thank you Lauren!

DOCSP-24594-Compass-auth-examples

8eb2bce

ltran-mdb2 added 4 commits January 10, 2025 12:46

DOCSP-24594-Compass-auth-examples

920f171

DOCSP-24594-Compass-auth-examples

3ae93e3

DOCSP-24594-Compass-auth-examples

901e4e8

DOCSP-24594-Compass-auth-examples

c04f4e8

ltran-mdb2 requested a review from jeff-allen-mongo January 13, 2025 14:40

jeff-allen-mongo reviewed Jan 13, 2025

View reviewed changes

ltran-mdb2 added 2 commits January 14, 2025 10:30

DOCSP-24594 copy edits

b5b58e4

DOCSP-24954 copy edits

7f29522

ltran-mdb2 requested a review from jeff-allen-mongo January 14, 2025 16:35

jeff-allen-mongo approved these changes Jan 14, 2025

View reviewed changes

ltran-mdb2 added 2 commits January 15, 2025 09:51

DOCSP-24594 copy edits

50e6844

DOCSP-24594 copy edits

48540de

jeff-allen-mongo reviewed Jan 15, 2025

View reviewed changes

betsybutton reviewed Jan 17, 2025

View reviewed changes

ltran-mdb2 added 2 commits January 23, 2025 19:01

DOCSP-24594 tech edits

3fbc615

DOCSP-24594 tech edits

de6caac

DOCSP-24594 tech edits

0b680bd

ltran-mdb2 requested a review from betsybutton January 24, 2025 01:35

betsybutton reviewed Jan 27, 2025

View reviewed changes

DOCSP-24594 update tls image

44087c3

ltran-mdb2 requested a review from betsybutton January 27, 2025 19:28

DOCSP-24594 updating screenshots

4ae08c2

betsybutton approved these changes Jan 27, 2025

View reviewed changes

		@@ -266,10 +266,19 @@ Procedure

		- (Optional) AWS Session Token

		The following screenshot shows the :guilabel:`Authentication`


		.. note::

		If you use the Standard Connection String Format to

		.. step:: (Optional) For advanced connection configuration options, click the :ref:`Advanced <advanced-connection-tab>` tab.

		.. step:: Click Connect.

DOCSP-24594-Compass-auth-examples #708

Are you sure you want to change the base?

DOCSP-24594-Compass-auth-examples #708

Conversation

ltran-mdb2 commented Jan 10, 2025 • edited Loading

DESCRIPTION

STAGING

JIRA

Self-Review Checklist

External Review Requirements

netlify bot commented Jan 10, 2025 • edited Loading

✅ Deploy Preview for docs-compass ready!

jeff-allen-mongo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ltran-mdb2 Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ltran-mdb2 commented Jan 14, 2025

jeff-allen-mongo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeff-allen-mongo Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeff-allen-mongo Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

betsybutton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ltran-mdb2 commented Jan 24, 2025 • edited Loading

betsybutton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

betsybutton left a comment

Choose a reason for hiding this comment

ltran-mdb2 commented Jan 10, 2025 •

edited

Loading

netlify bot commented Jan 10, 2025 •

edited

Loading

ltran-mdb2 Jan 14, 2025 •

edited

Loading

jeff-allen-mongo Jan 14, 2025 •

edited

Loading

jeff-allen-mongo Jan 15, 2025 •

edited

Loading

ltran-mdb2 commented Jan 24, 2025 •

edited

Loading