Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOCS] Updates alerting authorization docs with info on retaining API keys #132402

Merged
merged 8 commits into from
May 23, 2022
Merged

[DOCS] Updates alerting authorization docs with info on retaining API keys #132402

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
49fa86b
[DOCS] Updates alerting authorization docs with info on retaining API…
szabosteve May 18, 2022
287a22c
Merge branch 'main' into retaining.api.key.rules
szabosteve May 18, 2022
d84d37f
Merge branch 'main' into retaining.api.key.rules
szabosteve May 18, 2022
7793900
Merge branch 'main' into retaining.api.key.rules
szabosteve May 18, 2022
31569ed
Apply suggestions from code review
szabosteve May 19, 2022
f9120bf
[DOCS] Addresses feedback.
szabosteve May 19, 2022
daca621
[DOCS] Provides detail on when an API key could be missing.
szabosteve May 19, 2022
b93636f
Update docs/user/alerting/alerting-setup.asciidoc
szabosteve May 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 48 additions & 15 deletions docs/user/alerting/alerting-setup.asciidoc
View file
Open in desktop
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,52 @@ 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, it
generates a new key that has your security privileges.

You can update an API key manually in
**{stack-manage-app} > {rules-ui}** by selecting **Update API key** in
the actions menu of the respective rule.
szabosteve marked this conversation as resolved.
Show resolved Hide resolved

[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.
==============================================