From c94719baacb74ed54ab63b582505f88de401b096 Mon Sep 17 00:00:00 2001
From: shuangela <angela.shu@mongodb.com>
Date: Thu, 10 Apr 2025 12:24:05 -0400
Subject: [PATCH] DOCSP-48735-clarify-required-permissions (#719)

* clarify required permissions

* fix build errors

* fix build log

(cherry picked from commit db5824dfddaf7d1422018180b6f9a661fba4cf48)
---
 source/connecting/onprem-to-atlas.txt         |  8 ++--
 ...able-permissions-atlas-onprem-to-atlas.rst | 24 +++++++++++
 ...ermissions-self-hosted-onprem-to-atlas.rst | 41 +++++++++++++++++++
 3 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 source/includes/table-permissions-atlas-onprem-to-atlas.rst
 create mode 100644 source/includes/table-permissions-self-hosted-onprem-to-atlas.rst

diff --git a/source/connecting/onprem-to-atlas.txt b/source/connecting/onprem-to-atlas.txt
index f551b83d9..52cb2e2ba 100644
--- a/source/connecting/onprem-to-atlas.txt
+++ b/source/connecting/onprem-to-atlas.txt
@@ -45,13 +45,13 @@ Roles
 
 .. include:: /includes/fact-permissions-body.rst
 
-The self-managed permissions are:
+The self-managed permissions for the source cluster are:
 
-.. include:: /includes/table-permissions-self-hosted.rst
+.. include:: /includes/table-permissions-self-hosted-onprem-to-atlas.rst
 
-The Atlas permissions are:
+The Atlas permissions for the destination cluster are:
 
-.. include:: /includes/table-permissions-atlas.rst
+.. include:: /includes/table-permissions-atlas-onprem-to-atlas.rst
 
 Behavior
 --------
diff --git a/source/includes/table-permissions-atlas-onprem-to-atlas.rst b/source/includes/table-permissions-atlas-onprem-to-atlas.rst
new file mode 100644
index 000000000..68fb73d87
--- /dev/null
+++ b/source/includes/table-permissions-atlas-onprem-to-atlas.rst
@@ -0,0 +1,24 @@
+..
+   Comment: The nested lists need blank lines before and after each list
+            plus extra indents 
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 20
+
+   * - Sync Type
+     - Required Destination Permissions
+
+   * - Default
+     - - atlasAdmin
+       - :authaction:`bypassWriteBlockingMode`
+       
+   * - Dual write-blocking, reversing, or multiple reversals
+     - - atlasAdmin
+       - :authaction:`bypassWriteBlockingMode`
+
+For details on Atlas roles, see: :atlas:`Built-In Roles and Privileges
+</mongodb-users-roles-and-privileges/>`.
+
+To update Atlas user permissions, see:
+:atlas:`Manage Access to a Project </access/manage-project-access/>`.
\ No newline at end of file
diff --git a/source/includes/table-permissions-self-hosted-onprem-to-atlas.rst b/source/includes/table-permissions-self-hosted-onprem-to-atlas.rst
new file mode 100644
index 000000000..6c49483a4
--- /dev/null
+++ b/source/includes/table-permissions-self-hosted-onprem-to-atlas.rst
@@ -0,0 +1,41 @@
+..
+   Comment: The nested lists need extra indents.  Keep roles in alphabetic
+            order.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40
+
+   * - Sync Type
+     - Required Source Permissions
+
+   * - Default
+     - - :authrole:`backup`
+       - :authrole:`clusterMonitor`
+       - :authrole:`readAnyDatabase`
+
+   * - Dual Write-Blocking
+     - - :authrole:`backup`
+       - :authrole:`clusterManager`
+       - :authrole:`clusterMonitor`
+       - :authrole:`readWriteAnyDatabase`
+       - :authrole:`restore`
+
+   * - Reversing
+     - - :authrole:`backup`
+       - :authrole:`clusterManager`
+       - :authrole:`clusterMonitor`
+       - :authrole:`readWriteAnyDatabase`
+       - :authrole:`restore`
+
+   * - Multiple Reversals
+     - - :authrole:`backup`
+       - :authrole:`clusterManager`
+       - :authrole:`clusterMonitor`
+       - :authrole:`dbAdminAnyDatabase`
+       - :authrole:`readWriteAnyDatabase`
+       - :authrole:`restore`
+
+For details on server roles, see: :ref:`authorization`.
+
+To update user permissions, see: :dbcommand:`grantRolesToUser`.
\ No newline at end of file