[8.15] Update Reporting documentation: ES configuration, avoiding Token expiration (elastic#208257) (elastic#208757)

tsullivan · web-flow · commit f07aed137390 · 2025-01-29T15:07:00.000Z
# Backport This will backport the following commits from `main` to `8.15`: - [Update Reporting documentation: ES configuration, avoiding Token expiration (elastic#208257)](elastic#208257)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) \n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Tim Sullivan <tsullivan@users.noreply.github.com>"}},{"branch":"8.17","label":"v8.17.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/208716","number":208716,"state":"MERGED","mergeCommit":{"sha":"b5778932f5f1e2392660305200b49607e3034855","message":"[8.17] Update Reporting documentation: ES configuration, avoiding Token expiration (elastic#208257) (elastic#208716)\n\n# Backport\n\nThis will backport the following commits from `main` to `8.17`:\n- [Update Reporting documentation: ES configuration, avoiding Token\nexpiration (elastic#208257)](https://github.com/elastic/kibana/pull/208257)\n\n\n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Tim Sullivan <tsullivan@users.noreply.github.com>"}},{"branch":"8.x","label":"v8.18.0","branchLabelMappingKey":"^v8.18.0$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/208717","number":208717,"state":"MERGED","mergeCommit":{"sha":"8037864bc484c6e79952e590f37f44e27eef9f3a","message":"[8.x] Update Reporting documentation: ES configuration, avoiding Token expiration (elastic#208257) (elastic#208717)\n\n# Backport\n\nThis will backport the following commits from `main` to `8.x`:\n- [Update Reporting documentation: ES configuration, avoiding Token\nexpiration (elastic#208257)](https://github.com/elastic/kibana/pull/208257)\n\n\n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Tim Sullivan <tsullivan@users.noreply.github.com>"}}]}] BACKPORT-->
diff --git a/docs/setup/configuring-reporting.asciidoc b/docs/setup/configuring-reporting.asciidoc
@@ -17,6 +17,7 @@ to enable the {kib} server to have screenshotting capabilities.
 * <<securing-reporting>>
 * <<install-reporting-packages>>
 * <<set-reporting-server-host>>
+* <<reporting-elasticsearch-configuration>>
 
 [float]
 [[grant-user-access]]
@@ -246,3 +247,10 @@ address.
 
 For the most reliable configuration of PDF/PNG {report-features}, consider installing {kib} using <<docker, Docker>>, or
 using <<set-up-on-cloud, Elastic Cloud>>.
+
+[float]
+[[reporting-elasticsearch-configuration]]
+=== Ensure {es} allows built-in templates
+Reporting relies on {es} to install a mapping template for the data stream that stores reports. Ensure that {es} allows built-in
+templates to be installed by keeping the `stack.templates.enabled` setting at the default value of `true`. For more information, see
+{ref}/index-management-settings.html#stack-templates-enabled[Index management settings].
diff --git a/docs/user/reporting/reporting-csv-troubleshooting.asciidoc b/docs/user/reporting/reporting-csv-troubleshooting.asciidoc
@@ -88,5 +88,18 @@ image::https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt4758e67aa
 [[reporting-troubleshooting-csv-token-expired]]
 === Token expiration
 
-To avoid token expirations, use a type of authentication that doesn't expire (such as Basic auth) or run the export using scripts that query Elasticsearch directly.
-In a custom script, you have the ability to refresh the auth token as needed, such as once before each query.
+A relatively common type of error seen for CSV exports is: `security_exception Root causes: security_exception: token expired`.
+
+This error occurs in deployments that use token-based authentication (SAML tokens) when it takes too long to create the CSV report with the authentication cached in report job details.
+
+This means that the deployment is stable, but the size of the requested report is too large to complete within the time allowed by the authentication token available to the Reporting task.
+
+[float]
+[[avoid-token-expiration]]
+==== Avoiding token expiration
+
+You can use the following workarounds for this error:
+
+* Create smaller reports. Instead of creating one report that covers a large time range, create multiple reports that cover segmented time ranges.
+* Increase `xpack.security.authc.token.timeout`, which is set to `20m` by default.
+* To avoid token expirations completely, use a type of authentication that doesn't expire (such as Basic auth), or run the export using scripts that query {es} directly.
