QuickStart and Tutorial for QE and CSFLE: Update the required permissions and move to an include (#5597) (#6054)

MongoCaleb · web-flow · commit 7454fcdc990f · 2024-01-29T15:02:18.000-05:00
* Update required permissions and move to an include

* Simplify the permissions include

* fix typo and formatting

* add note about convention and move most to include
diff --git a/source/core/queryable-encryption/quick-start.txt b/source/core/queryable-encryption/quick-start.txt
@@ -90,23 +90,7 @@ Procedure
          .. tab::
             :tabid: shell
 
-            - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}.
-              Set this variable to ``"local"`` for this tutorial.
-            - **uri** - Your MongoDB deployment connection URI. Set your connection
-              URI in the ``MONGODB_URI`` environment variable or replace the value
-              directly.
-            - **keyVaultDatabaseName** - The database in MongoDB where your data
-              encryption keys (DEKs) will be stored. Set this variable
-              to ``"encryption"``.
-            - **keyVaultCollectionName** - The collection in MongoDB where your DEKs
-              will be stored. Set this variable to ``"__keyVault"``.
-            - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
-              be stored. Set this variable to the values of the ``keyVaultDatabaseName``
-              and ``keyVaultCollectionName`` variables, separated by a period.
-            - **encryptedDatabaseName** - The database in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"medicalRecords"``.
-            - **encryptedCollectionName** - The collection in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"patients"``.
+            .. include:: /includes/qe-tutorials/qe-quick-start.rst
 
             You can declare these variables by using the following code:
 
@@ -119,23 +103,7 @@ Procedure
          .. tab::
             :tabid: nodejs
 
-            - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}.
-              Set this variable to ``"local"`` for this tutorial.
-            - **uri** - Your MongoDB deployment connection URI. Set your connection
-              URI in the ``MONGODB_URI`` environment variable or replace the value
-              directly.
-            - **keyVaultDatabaseName** - The database in MongoDB where your data
-              encryption keys (DEKs) will be stored. Set this variable
-              to ``"encryption"``.
-            - **keyVaultCollectionName** - The collection in MongoDB where your DEKs
-              will be stored. Set this variable to ``"__keyVault"``.
-            - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
-              be stored. Set this variable to the values of the ``keyVaultDatabaseName``
-              and ``keyVaultCollectionName`` variables, separated by a period.
-            - **encryptedDatabaseName** - The database in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"medicalRecords"``.
-            - **encryptedCollectionName** - The collection in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"patients"``.
+            .. include:: /includes/qe-tutorials/qe-quick-start.rst
 
             You can declare these variables by using the following code:
 
@@ -157,7 +125,8 @@ Procedure
               encryption keys (DEKs) will be stored. Set this variable
               to ``"encryption"``.
             - **key_vault_collection_name** - The collection in MongoDB where your DEKs
-              will be stored. Set this variable to ``"__keyVault"``.
+              will be stored. Set this variable to ``"__keyVault"``, which is the 
+              convention to help prevent mistaking it for a user collection.
             - **key_vault_namespace** - The namespace in MongoDB where your DEKs will
               be stored. Set this variable to the values of the ``key_vault_database_name``
               and ``key_vault_collection_name`` variables, separated by a period.
@@ -177,23 +146,7 @@ Procedure
          .. tab::
             :tabid: java-sync
 
-            - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}.
-              Set this variable to ``"local"`` for this tutorial.
-            - **uri** - Your MongoDB deployment connection URI. Set your connection
-              URI in the ``MONGODB_URI`` environment variable or replace the value
-              directly.
-            - **keyVaultDatabaseName** - The database in MongoDB where your data
-              encryption keys (DEKs) will be stored. Set this variable
-              to ``"encryption"``.
-            - **keyVaultCollectionName** - The collection in MongoDB where your DEKs
-              will be stored. Set this variable to ``"__keyVault"``.
-            - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
-              be stored. Set this variable to the values of the ``keyVaultDatabaseName``
-              and ``keyVaultCollectionName`` variables, separated by a period.
-            - **encryptedDatabaseName** - The database in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"medicalRecords"``.
-            - **encryptedCollectionName** - The collection in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"patients"``.
+            .. include:: /includes/qe-tutorials/qe-quick-start.rst
 
             You can declare these variables by using the following code:
 
@@ -206,23 +159,7 @@ Procedure
          .. tab::
             :tabid: go
 
-            - **kmsProviderName** - The KMS you're using to store your {+cmk-long+}.
-              Set this variable to ``"local"`` for this tutorial.
-            - **uri** - Your MongoDB deployment connection URI. Set your connection
-              URI in the ``MONGODB_URI`` environment variable or replace the value
-              directly.
-            - **keyVaultDatabaseName** - The database in MongoDB where your data
-              encryption keys (DEKs) will be stored. Set this variable
-              to ``"encryption"``.
-            - **keyVaultCollectionName** - The collection in MongoDB where your DEKs
-              will be stored. Set this variable to ``"__keyVault"``.
-            - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
-              be stored. Set this variable to the values of the ``keyVaultDatabaseName``
-              and ``keyVaultCollectionName`` variables, separated by a period.
-            - **encryptedDatabaseName** - The database in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"medicalRecords"``.
-            - **encryptedCollectionName** - The collection in MongoDB where your encrypted
-              data will be stored. Set this variable to ``"patients"``.
+            .. include:: /includes/qe-tutorials/qe-quick-start.rst
 
             You can declare these variables by using the following code:
 
@@ -241,7 +178,8 @@ Procedure
               encryption keys (DEKs) will be stored. Set the value of ``keyVaultDatabaseName``
               to ``"encryption"``.
             - **keyVaultCollectionName** - The collection in MongoDB where your DEKs
-              will be stored. Set the value of ``keyVaultCollectionName`` to ``"__keyVault"``.
+              will be stored. Set this variable to ``"__keyVault"``, which is the 
+              convention to help prevent mistaking it for a user collection.
             - **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
               be stored. Set ``keyVaultNamespace`` to a new ``CollectionNamespace`` object whose name
               is the values of the ``keyVaultDatabaseName`` and ``keyVaultCollectionName`` variables,
@@ -264,10 +202,7 @@ Procedure
 
       .. important:: {+key-vault-long-title+} Namespace Permissions
 
-         The {+key-vault-long+} is in the ``encryption.__keyVault``
-         namespace. Ensure that the database user your application uses to connect
-         to MongoDB has :ref:`ReadWrite <manual-reference-role-read-write>`
-         permissions on this namespace.
+         .. include:: /includes/note-key-vault-permissions
 
       .. include:: /includes/queryable-encryption/env-variables.rst
 
diff --git a/source/includes/note-key-vault-permissions.rst b/source/includes/note-key-vault-permissions.rst
@@ -0,0 +1,5 @@
+To complete this tutorial, the database user your application uses to connect to 
+MongoDB must have :authrole:`dbAdmin` permissions on the following namespaces:
+
+- ``encryption.__keyVault``
+- ``medicalRecords`` database
diff --git a/source/includes/qe-tutorials/qe-quick-start.rst b/source/includes/qe-tutorials/qe-quick-start.rst
@@ -0,0 +1,18 @@
+- **kmsProviderName** - The KMS you're using to store your {+cmk-long+}.
+  Set this variable to ``"local"`` for this tutorial.
+- **uri** - Your MongoDB deployment connection URI. Set your connection
+  URI in the ``MONGODB_URI`` environment variable or replace the value
+  directly.
+- **keyVaultDatabaseName** - The database in MongoDB where your data
+  encryption keys (DEKs) will be stored. Set this variable
+  to ``"encryption"``.
+- **keyVaultCollectionName** - The collection in MongoDB where your DEKs
+  will be stored. Set this variable to ``"__keyVault"``, which is the convention
+  to help prevent mistaking it for a user collection.
+- **keyVaultNamespace** - The namespace in MongoDB where your DEKs will
+  be stored. Set this variable to the values of the ``keyVaultDatabaseName``
+  and ``keyVaultCollectionName`` variables, separated by a period.
+- **encryptedDatabaseName** - The database in MongoDB where your encrypted
+  data will be stored. Set this variable to ``"medicalRecords"``.
+- **encryptedCollectionName** - The collection in MongoDB where your encrypted
+  data will be stored. Set this variable to ``"patients"``.
diff --git a/source/includes/queryable-encryption/quick-start/dek.rst b/source/includes/queryable-encryption/quick-start/dek.rst
@@ -80,10 +80,7 @@
 
       .. note:: {+key-vault-long-title+} Namespace Permissions
 
-         The {+key-vault-long+} is in the ``encryption.__keyVault``
-         namespace. Ensure that the database user your application uses to connect
-         to MongoDB has :ref:`ReadWrite <manual-reference-role-read-write>`
-         permissions on this namespace.
+         .. include:: /includes/note-key-vault-permissions
 
       .. tabs-drivers::
 
diff --git a/source/includes/queryable-encryption/tutorials/exp/dek.rst b/source/includes/queryable-encryption/tutorials/exp/dek.rst
@@ -71,10 +71,7 @@
 
       .. note:: {+key-vault-long-title+} Namespace Permissions
 
-         The {+key-vault-long+} is in the ``encryption.__keyVault``
-         namespace. Ensure that the database user your application uses to connect
-         to MongoDB has :ref:`ReadWrite <manual-reference-role-read-write>`
-         permissions on this namespace.
+         .. include:: /includes/note-key-vault-permissions
 
       .. tabs-drivers::
 
diff --git a/source/includes/quick-start/dek.rst b/source/includes/quick-start/dek.rst
@@ -69,10 +69,7 @@
 
       .. note:: {+key-vault-long-title+} Namespace Permissions
 
-         The {+key-vault-long+} is in the ``encryption.__keyVault``
-         namespace. Ensure that the database user your application uses to connect
-         to MongoDB has :ref:`ReadWrite <manual-reference-role-read-write>`
-         permissions on this namespace.
+         .. include:: /includes/note-key-vault-permissions
 
       .. tabs-drivers::
 
