[Alerts][Doc] Added README documentation for API key invalidation con…

…figuration options. (#92757) * [Alerts][Doc] Added README documentation for API key invalidation configuration options. * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> Co-authored-by: gchaps <[email protected]>
elastic · Feb 25, 2021 · ad19f82 · ad19f82
1 parent 3894ecf
commit ad19f82
Showing 1 changed file with 12 additions and 0 deletions.
diff --git a/x-pack/plugins/alerts/README.md b/x-pack/plugins/alerts/README.md
@@ -13,6 +13,7 @@ Table of Contents
 - [Kibana alerting](#kibana-alerting)
 	- [Terminology](#terminology)
 	- [Usage](#usage)
+	- [Alerts API keys](#alerts-api-keys)
 	- [Limitations](#limitations)
 	- [Alert types](#alert-types)
 		- [Methods](#methods)
@@ -53,6 +54,17 @@ A Kibana alert detects a condition and executes one or more actions when that co
 2. Configure feature level privileges using RBAC 
 3. Create an alert using the RESTful API [Documentation](https://www.elastic.co/guide/en/kibana/master/alerts-api-update.html) (see alerts -> create).
 
+## Alerts API keys
+
+When we create an alert, we generate a new API key.
+
+When we update, enable, or disable an alert, we must invalidate the old API key and create a new one.
+
+To manage the invalidation process for API keys, we use the saved object `api_key_pending_invalidation`.  This object stores all API keys that were marked for invalidation when alerts were updated.
+For security plugin invalidation, we schedule a task to check if the`api_key_pending_invalidation` saved object contains new API keys that are marked for invalidation earlier than the configured delay.  The default value for running the task is 5 mins.
+To change the schedule for the invalidation task, use the kibana.yml configuration option `xpack.alerts.invalidateApiKeysTask.interval`.
+To change the default delay for the API key invalidation, use the kibana.yml configuration option `xpack.alerts.invalidateApiKeysTask.removalDelay`.
+
 ## Limitations
 
 When security is enabled, an SSL connection to Elasticsearch is required in order to use alerting.