Skip to content

DOCSP-24594-Compass-auth-examples #708

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 16 commits into from
Jan 28, 2025
Merged

DOCSP-24594-Compass-auth-examples #708

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
8eb2bce
DOCSP-24594-Compass-auth-examples
ltran-mdb2 Jan 10, 2025
920f171
DOCSP-24594-Compass-auth-examples
ltran-mdb2 Jan 10, 2025
3ae93e3
DOCSP-24594-Compass-auth-examples
ltran-mdb2 Jan 10, 2025
901e4e8
DOCSP-24594-Compass-auth-examples
ltran-mdb2 Jan 10, 2025
c04f4e8
DOCSP-24594-Compass-auth-examples
ltran-mdb2 Jan 10, 2025
b5b58e4
DOCSP-24594 copy edits
ltran-mdb2 Jan 14, 2025
7f29522
DOCSP-24954 copy edits
ltran-mdb2 Jan 14, 2025
50e6844
DOCSP-24594 copy edits
ltran-mdb2 Jan 15, 2025
48540de
DOCSP-24594 copy edits
ltran-mdb2 Jan 15, 2025
3fbc615
DOCSP-24594 tech edits
ltran-mdb2 Jan 24, 2025
de6caac
DOCSP-24594 tech edits
ltran-mdb2 Jan 24, 2025
0b680bd
DOCSP-24594 tech edits
ltran-mdb2 Jan 24, 2025
44087c3
DOCSP-24594 update tls image
ltran-mdb2 Jan 27, 2025
4ae08c2
DOCSP-24594 updating screenshots
ltran-mdb2 Jan 27, 2025
9359bf8
DOCSP-24594 fixing build
ltran-mdb2 Jan 28, 2025
9238a00
DOCSP-24594 fixing build
ltran-mdb2 Jan 28, 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
8 changes: 8 additions & 0 deletions source/connect/advanced-connection-options/advanced-connection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,14 @@ Procedure
read preference option.
- Any specified tag sets.

The following screenshot shows the :guilabel:`Advanced`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

tab configured with the read preference of :guilabel:`Secondary
Preferred`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


.. figure:: /images/authentication/secondary-preferred.png
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

@ltran-mdb2 ltran-mdb2 Jan 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

:figwidth: 662px
:alt: Screenshot of Compass configured to connect with read preference of secondary preferred

.. seealso::

- :manual:`Read Preferrence </core/read-preference/#read-preference>`.
Expand Down
9 changes: 9 additions & 0 deletions source/connect/advanced-connection-options/authentication-connection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,10 +266,19 @@ Procedure

- (Optional) AWS Session Token

The following screenshot shows the :guilabel:`Authentication`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

tab configured for username and password authentication with
SCRAM-SHA-256.

.. figure:: /images/authentication/authentication-configuration.png
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

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

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

.. step:: Click Connect.


Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

.. seealso::

To disconnect from your deployment, see :ref:`<disconnect-tab>`.
21 changes: 20 additions & 1 deletion source/connect/advanced-connection-options/general-connection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,20 @@ Procedure
* - mongodb
- :manual:`Standard Connection String Format </reference/connection-string/>`.
The standard format of the MongoDB connection URI is used to
connect to a MongoDB deployment by specifying its hosts directly.
connect to a MongoDB deployment by specifying its hosts
directly.

Use this option to connect to standalone, replica set,
or a sharded cluster

.. note::

If you use the Standard Connection String Format to
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nit]

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed!

connect to an `Atlas
<https://www.mongodb.com/cloud/atlas>`__ deployment,
you must turn on TLS/SSL in the
:guilabel:`TLS/SSL` tab of the :guilabel:`New
Connection` modal.

* - mongodb+srv
- :manual:`DNS Seed List Connection Format
Expand Down Expand Up @@ -86,6 +99,12 @@ Procedure
of a replica set, your write operations fail because it is not the
primary member.

The following screenshot shows the :guilabel:`General` tab
configured for an Atlas cluster.

.. figure:: /images/authentication/new-atlas-connection.png
:alt: Screenshot of Compass configured to connect to an example Atlas cluster

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

.. step:: Click Connect.
Expand Down
10 changes: 9 additions & 1 deletion source/connect/advanced-connection-options/tls-ssl-connection.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,15 @@ Procedure
.. warning::

Enabling ``tlsInsecure``, ``tlsAllowInvalidHostnames``, and
``tlsAllowInvalidCertificates`` may cause a security vulnerabilty.
``tlsAllowInvalidCertificates`` may cause a security
vulnerabilty.

The following screenshot shows the :guilabel:`TLS /
SSL` tab configured for a cluster with TLS/SSL enabled.

.. figure:: /images/authentication/tls-ssl-configuration.png
:figwidth: 662px
:alt: Screenshot of Compass configured to connect to an example cluster with TLS/SSL

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

Expand Down
Binary file added source/images/authentication/New-Atlas-Connection.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/authentication/authentication-configuration.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/authentication/new-atlas-connection.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/authentication/secondary-preferred.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/authentication/tls-ssl-configuration.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading