From a2d496ce63f96e7190e0ae9f7214eb093d9f907f Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Tue, 24 Oct 2023 13:18:17 +0200
Subject: [PATCH] [8.7] docs: Document privileges to read RUM source maps;
 Update examples (backport #11741) (#11895)

* docs: Document privileges to read RUM source maps; Update examples (#11741)

* Document required privileges to read RUM source map from ES since 8.7.

* Update API key creation examples, add agentcfg role to it.

(cherry picked from commit 00fb30eb6fe1b5c41f7e05d7b2a7e6f484cfd4cc)

# Conflicts:
#	docs/legacy/configuration-rum.asciidoc
Signed-off-by: Carson Ip <carson.ip@elastic.co>

* Fix conflict

Signed-off-by: Carson Ip <carson.ip@elastic.co>

---------

Signed-off-by: Carson Ip <carson.ip@elastic.co>
Co-authored-by: Carson Ip <carsonip@users.noreply.github.com>
Co-authored-by: Carson Ip <carson.ip@elastic.co>
---
 docs/legacy/api-keys.asciidoc          | 38 +++++++++++++++++++++-----
 docs/legacy/configuration-rum.asciidoc |  2 +-
 docs/legacy/feature-roles.asciidoc     | 37 ++++++++++++++++++++++---
 3 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/docs/legacy/api-keys.asciidoc b/docs/legacy/api-keys.asciidoc
index cab1e68dceb..a33b71c0b3b 100644
--- a/docs/legacy/api-keys.asciidoc
+++ b/docs/legacy/api-keys.asciidoc
@@ -37,12 +37,24 @@ In the role descriptors box, assign the appropriate privileges to the new API ke
             {
                 "names": ["{beat_default_index_prefix}-*"],
                 "privileges": ["create_index", "create_doc"]
-            },
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+        "index": [
             {
-                "names": ["{beat_default_index_prefix}-*sourcemap"],
+                "names": [".apm-source-map"],
                 "privileges": ["read"]
-            },
-      ]
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+        "index": [
+            {
+                "names": [".apm-agent-configuration"],
+                "privileges": ["read"]
+            }
+        ]
     }
 }
 ----
@@ -126,11 +138,23 @@ POST /_security/api_key
         {
           "names": ["{beat_default_index_prefix}-*"],
           "privileges": ["create_index", "create_doc"]
-        },
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+      "index": [
+        {
+          "names": [".apm-source-map"],
+          "privileges": ["read"]
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+      "index": [
         {
-          "names": ["{beat_default_index_prefix}-*sourcemap"],
+          "names": [".apm-agent-configuration"],
           "privileges": ["read"]
-        },
+        }
       ]
     }
   }
diff --git a/docs/legacy/configuration-rum.asciidoc b/docs/legacy/configuration-rum.asciidoc
index b0db2dd8731..3bfd4d05295 100644
--- a/docs/legacy/configuration-rum.asciidoc
+++ b/docs/legacy/configuration-rum.asciidoc
@@ -139,7 +139,7 @@ Default: `"^/webpack"` (excludes stack trace frames that have a filename startin
 ==== `source_mapping.enabled`
 Used to enable/disable <<sourcemaps,source mapping>> for RUM events.
 When enabled, the APM Server needs additional privileges to read source maps.
-See <<privileges-to-publish-events>> for more details.
+See <<privileges-rum-source-mapping>> for more details.
 
 Default: `true`
 
diff --git a/docs/legacy/feature-roles.asciidoc b/docs/legacy/feature-roles.asciidoc
index b5d3b458564..443cb088c80 100644
--- a/docs/legacy/feature-roles.asciidoc
+++ b/docs/legacy/feature-roles.asciidoc
@@ -16,6 +16,7 @@ information, and another for viewing it.
 * <<privileges-api-key,API key role>>: To create and manage API keys.
 * <<privileges-agent-central-config,Central configuration management role>>: To view
 APM Agent central configurations.
+* <<privileges-rum-source-mapping,RUM source mapping role>>: To read RUM source maps.
 
 {es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a
 subset of the privileges needed by APM users.
@@ -64,12 +65,10 @@ that has the following privileges:
 |Write events into {es}
 |====
 
-. If <<configuration-rum,real user monitoring>> is enabled, additional privileges are required to read source maps.
-See {kibana-ref}/rum-sourcemap-api.html[RUM source map API] for more details.
-Assign these extra privileges to the *general writer role*.
-
 . Assign the *general writer role* to users who need to publish APM data.
 
+. If <<configuration-rum,real user monitoring>> is enabled, create a separate <<privileges-rum-source-mapping,RUM source mapping role>>.
+
 ////
 ***********************************  ***********************************
 ***********************************  ***********************************
@@ -333,6 +332,36 @@ which requires the following privileges:
 TIP: Looking for privileges and roles needed to use central configuration from the {apm-app} or {apm-app} API?
 See {kibana-ref}/apm-app-central-config-user.html[{apm-app} central configuration user].
 
+[[privileges-rum-source-map]]
+=== Grant privileges and roles needed for reading source maps
+
+++++
+<titleabbrev>Create a _source map_ user</titleabbrev>
+++++
+
+[[privileges-rum-source-mapping]]
+==== APM Server RUM source mapping
+
+If <<configuration-rum,real user monitoring>> is enabled, additional privileges are required to read source maps.
+
+To grant an APM Server user with the required privileges for reading RUM source maps from {es} directly without {kib},
+assign the user the following privileges:
+
+[options="header"]
+|====
+|Type | Privilege | Purpose
+
+|Index
+|`read` on `.apm-source-map` index
+|Allow {beatname_uc} to read RUM source maps from {es}
+|====
+
+The above privileges should be sufficient for RUM source mapping to work properly
+as long as {beatname_uc} communicates with {es} successfully.
+If it fails, it may fallback to read source maps via {kib} if configured,
+which requires additional {kib} privileges.
+See {kibana-ref}/rum-sourcemap-api.html[RUM source map API] for more details.
+
 ////
 ***********************************  ***********************************
 ***********************************  ***********************************