Skip to content

Commit

Permalink
[DOCS] Updates alerting authorization docs with info on retaining API…
Browse files Browse the repository at this point in the history
… keys (elastic#132402)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
  • Loading branch information
szabosteve and lcawl authored May 23, 2022
1 parent 40df1f3 commit 9649307
Showing 1 changed file with 49 additions and 15 deletions.
64 changes: 49 additions & 15 deletions docs/user/alerting/alerting-setup.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,47 @@
<titleabbrev>Set up</titleabbrev>
++++

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 <<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>> setting.
* For emails to have a footer with a link back to {kib}, set the <<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.
* In the kibana.yml configuration file, add the
<<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>>
setting.
* For emails to have a footer with a link back to {kib}, set the
<<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.

If you are using an *on-premises* Elastic Stack deployment with <<using-kibana-with-security, *security*>>:
If you are using an *on-premises* Elastic Stack deployment with
<<using-kibana-with-security, *security*>>:

* 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 <<alerting-production-considerations,Alerting production considerations>>.
When relying on alerting and actions as mission critical services, make sure you
follow the
<<alerting-production-considerations,Alerting production considerations>>.

See <<alerting-scaling-guidance>> for more information on the scalability of Alerting.
See <<alerting-scaling-guidance>> 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
* <<xpack-apm,*APM*>>
Expand All @@ -43,31 +55,53 @@ To access alerting in a space, a user must have access to one of the following f
* <<xpack-siem,*Security*>>
* <<uptime-app,*Uptime*>>

See <<kibana-feature-privileges, feature privileges>> 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 <<kibana-feature-privileges, feature privileges>> 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. <<action-settings>> allows you to disable certain <<action-types>> 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. <<action-settings>> allows you to disable certain
<<action-types>> 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 <<api-keys,API key>> 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 <<api-keys,API key>> 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.
==============================================

0 comments on commit 9649307

Please sign in to comment.