From 9649307334f64ee594c42614eeb3d0c10a38759f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 23 May 2022 10:12:54 +0200 Subject: [PATCH] [DOCS] Updates alerting authorization docs with info on retaining API keys (#132402) Co-authored-by: Lisa Cawley --- docs/user/alerting/alerting-setup.asciidoc | 64 +++++++++++++++++----- 1 file changed, 49 insertions(+), 15 deletions(-) diff --git a/docs/user/alerting/alerting-setup.asciidoc b/docs/user/alerting/alerting-setup.asciidoc index 6643f8d0ec8708..9e3fb54e39444f 100644 --- a/docs/user/alerting/alerting-setup.asciidoc +++ b/docs/user/alerting/alerting-setup.asciidoc @@ -5,35 +5,47 @@ Set up ++++ -Alerting is automatically enabled in {kib}, but might require some additional configuration. +Alerting is automatically enabled in {kib}, but might require some additional +configuration. [float] [[alerting-prerequisites]] === Prerequisites If you are using an *on-premises* Elastic Stack deployment: -* In the kibana.yml configuration file, add the <> setting. -* For emails to have a footer with a link back to {kib}, set the <> configuration setting. +* In the kibana.yml configuration file, add the +<> +setting. +* For emails to have a footer with a link back to {kib}, set the +<> configuration setting. -If you are using an *on-premises* Elastic Stack deployment with <>: +If you are using an *on-premises* Elastic Stack deployment with +<>: -* If you are unable to access {kib} Alerting, ensure that you have not {ref}/security-settings.html#api-key-service-settings[explicitly disabled API keys]. +* If you are unable to access {kib} Alerting, ensure that you have not +{ref}/security-settings.html#api-key-service-settings[explicitly disabled API keys]. -The alerting framework uses queries that require the `search.allow_expensive_queries` setting to be `true`. See the scripts {ref}/query-dsl-script-query.html#_allow_expensive_queries_4[documentation]. +The alerting framework uses queries that require the +`search.allow_expensive_queries` setting to be `true`. See the scripts +{ref}/query-dsl-script-query.html#_allow_expensive_queries_4[documentation]. [float] [[alerting-setup-production]] === Production considerations and scaling guidance -When relying on alerting and actions as mission critical services, make sure you follow the <>. +When relying on alerting and actions as mission critical services, make sure you +follow the +<>. -See <> for more information on the scalability of Alerting. +See <> for more information on the scalability of +Alerting. [float] [[alerting-security]] === Security -To access alerting in a space, a user must have access to one of the following features: +To access alerting in a space, a user must have access to one of the following +features: * Alerting * <> @@ -43,31 +55,53 @@ To access alerting in a space, a user must have access to one of the following f * <> * <> -See <> for more information on configuring roles that provide access to these features. -Also note that a user will need +read+ privileges for the *Actions and Connectors* feature to attach actions to a rule or to edit a rule that has an action attached to it. +See <> for more information on +configuring roles that provide access to these features. +Also note that a user will need +read+ privileges for the +*Actions and Connectors* feature to attach actions to a rule or to edit a rule +that has an action attached to it. [float] [[alerting-restricting-actions]] ==== Restrict actions -For security reasons you may wish to limit the extent to which {kib} can connect to external services. <> allows you to disable certain <> and allowlist the hostnames that {kib} can connect with. +For security reasons you may wish to limit the extent to which {kib} can connect +to external services. <> allows you to disable certain +<> and allowlist the hostnames that {kib} can connect with. [float] [[alerting-spaces]] === Space isolation -Rules and connectors are isolated to the {kib} space in which they were created. A rule or connector created in one space will not be visible in another. +Rules and connectors are isolated to the {kib} space in which they were created. +A rule or connector created in one space will not be visible in another. [float] [[alerting-authorization]] === Authorization -Rules are authorized using an <> associated with the last user to edit the rule. This API key captures a snapshot of the user's privileges at the time of edit and is subsequently used to run all background tasks associated with the rule, including condition checks like {es} queries and triggered actions. The following rule actions will re-generate the API key: +Rules are authorized using an <> associated with the last user +to edit the rule. This API key captures a snapshot of the user's privileges at +the time of the edit. They are subsequently used to run all background tasks +associated with the rule, including condition checks like {es} queries and +triggered actions. The following rule actions will re-generate the API key: * Creating a rule * Updating a rule +When you disable a rule, it retains the associated API key which is re-used when +the rule is enabled. If the API key is missing when you enable the rule (for +example, in the case of imported rules), it generates a new key that has your +security privileges. + +You can update an API key manually in +**{stack-manage-app} > {rules-ui}** or in the rule details page by selecting +**Update API key** in the actions menu. + [IMPORTANT] ============================================== -If a rule requires certain privileges, such as index privileges, to run, and a user without those privileges updates the rule, the rule will no longer function. Conversely, if a user with greater or administrator privileges modifies the rule, it will begin running with increased privileges. +If a rule requires certain privileges, such as index privileges, to run, and a +user without those privileges updates the rule, the rule will no longer +function. Conversely, if a user with greater or administrator privileges +modifies the rule, it will begin running with increased privileges. ==============================================