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 00fb30e) # Conflicts: # docs/legacy/configuration-rum.asciidoc Signed-off-by: Carson Ip <[email protected]>
elastic · Oct 19, 2023 · 852377f · 852377f
1 parent b3d2e66
commit 852377f
Show file tree

Hide file tree

Showing 3 changed files with 190 additions and 11 deletions.
diff --git 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
@@ -53,6 +53,132 @@ Anonymous authentication is required as the RUM agent runs in the browser.
 ====
 
 [float]
+<<<<<<< HEAD:docs/legacy/configuration-rum.asciidoc
+=======
+[[rum-allow-origins]]
+== Allowed Origins
+A list of permitted origins for RUM support.
+User-agents send an Origin header that will be validated against this list.
+This is done automatically by modern browsers as part of the https://www.w3.org/TR/cors/[CORS specification].
+An origin is made of a protocol scheme, host and port, without the URL path.
+
+Default: `['*']` (allows everything). (text)
+
+|====
+| APM Server binary | `apm-server.rum.allow_origins`
+| Fleet-managed     | `Allowed Origins`
+|====
+
+[float]
+[[rum-allow-headers]]
+== Access-Control-Allow-Headers
+HTTP requests made from the RUM agent to the APM Server are limited in the HTTP headers they are allowed to have.
+If any other headers are added, the request will be rejected by the browser due to Cross-Origin Resource Sharing (CORS) restrictions.
+Use this setting to allow additional headers.
+The default list of allowed headers includes "Content-Type", "Content-Encoding", and "Accept";
+custom values configured here are appended to the default list and used as the value for the `Access-Control-Allow-Headers` header.
+
+Default: `[]`. (text)
+
+|====
+| APM Server binary | `apm-server.rum.allow_headers`
+| Fleet-managed     | `Access-Control-Allow-Headers`
+|====
+
+[float]
+[[rum-response-headers]]
+== Custom HTTP response headers
+Custom HTTP headers to add to RUM responses.
+This can be useful for security policy compliance.
+
+Values set for the same key will be concatenated.
+
+Default: none. (text)
+
+|====
+| APM Server binary | `apm-server.rum.response_headers`
+| Fleet-managed     | `Custom HTTP response headers`
+|====
+
+[float]
+[[rum-library-pattern]]
+== Library Frame Pattern
+RegExp to be matched against a stack trace frame's `file_name` and `abs_path` attributes.
+If the RegExp matches, the stack trace frame is considered to be a library frame.
+When source mapping is applied, the `error.culprit` is set to reflect the _function_ and the _filename_
+of the first non library frame.
+This aims to provide an entry point for identifying issues.
+
+Default: `"node_modules|bower_components|~"`. (text)
+
+|====
+| APM Server binary | `apm-server.rum.library_pattern`
+| Fleet-managed     | `Library Frame Pattern`
+|====
+
+[float]
+== Exclude from grouping
+RegExp to be matched against a stack trace frame's `file_name`.
+If the RegExp matches, the stack trace frame is excluded from being used for calculating error groups.
+
+Default: `"^/webpack"` (excludes stack trace frames that have a filename starting with `/webpack`). (text)
+
+|====
+| APM Server binary | `apm-server.rum.exclude_from_grouping`
+| Fleet-managed     | `Exclude from grouping`
+|====
+
+
+[float]
+[[rum-source-map]]
+= Source map configuration options
+
+****
+image:./binary-yes-fm-no.svg[supported deployment methods]
+
+Source maps are supported by all APM Server deployment methods, however,
+the options in this section are only supported by the APM Server binary.
+****
+
+[[config-sourcemapping-enabled]]
+[float]
+== `source_mapping.enabled`
+Used to enable/disable <<source-map-how-to,source mapping>> for RUM events.
+When enabled, the APM Server needs additional privileges to read source maps.
+See <<privileges-rum-source-mapping>> for more details.
+
+Default: `true`
+
+[[config-sourcemapping-elasticsearch]]
+[float]
+== `source_mapping.elasticsearch`
+Configure the {es} source map retrieval location, taking the same options as <<elasticsearch-output,output.elasticsearch>>.
+This must be set when using an output other than {es}, and that output is writing to {es}.
+Otherwise leave this section empty.
+
+[[rum-sourcemap-cache]]
+[float]
+== `source_mapping.cache.expiration`
+If a source map has been uploaded to the APM Server,
+<<source-map-how-to,source mapping>> is automatically applied to documents sent to the RUM endpoint.
+Source maps are fetched from {es} and then kept in an in-memory cache for the configured time.
+Values configured without a time unit are treated as seconds.
+
+Default: `5m` (5 minutes)
+
+[float]
+== `source_mapping.index_pattern`
+Previous versions of APM Server stored source maps in `apm-%{[observer.version]}-sourcemap` indices.
+Search source maps stored in an older version with this setting.
+
+Default: `"apm-*-sourcemap*"`
+
+[float]
+[[rum-deprecated]]
+= Deprecated configuration options
+
+[float]
+>>>>>>> 00fb30eb6 (docs: Document privileges to read RUM source maps; Update examples (#11741)):docs/configure/rum.asciidoc
 [[event_rate.limit]]
 ==== `event_rate.limit`
 

diff --git 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.
+
 ////
 ***********************************  ***********************************
 ***********************************  ***********************************