Rule, action policy, and workflow authorization

Kibana Universal Alerting authorizes rules, action policies, and workflows with different credentials. Knowing which credential applies to each operation helps you diagnose authorization errors and keep credentials current.

The type of operation determines which credential authorizes it.

Operation How it's authorized
Rule runs The rule runs with an API key based on the credentials of the user who created the rule, last enabled it, or last rotated its key. The key determines what data the rule can query, and editing the rule doesn't replace it. The key is an Elasticsearch API key, except in Serverless where it is an Elastic Cloud API key. To learn how each key type handles role changes, refer to Which type of API key a rule uses. To replace the key with one based on your credentials, refer to Rotate a rule's API key.
Action policy evaluates and dispatches Uses different credentials at different phases. Refer to How action policies authorize a workflow run.
Workflow steps run The workflow runs with the action policy's API key, so its steps can do only what that key's privileges allow.

Rules run with an Elasticsearch API key, except in Serverless, where they run with an Elastic Cloud API key. A rule's key owner is the user who created the rule, last enabled it, or last rotated its key. Each key type records the key owner's access differently, so the same role change affects a rule differently depending on its key type.

If you create or enable a rule through the Kibana API while authenticated with your own API key, Kibana creates a separate key for the rule instead of reusing yours.

A rule's Elastic Cloud API key records the key owner's roles at the time Kibana creates the key, but not the privileges those roles grant. Each time the rule runs, it uses the current privileges of those roles.

The following table shows how common role changes affect the rule and what to do:

Change Effect on the rule What to do
An administrator edits one of the recorded roles The rule uses the updated privileges on its next run. You don't need to do anything.
An administrator assigns the key owner a new role The rule doesn't get the new role's privileges. Rotate the rule's API key as a user who has the new role.
An administrator deletes a custom role that the key recorded The rule loses that role's privileges and might fail. Rotate the rule's API key as a user who has the privileges the rule needs.
The key owner leaves your organization The rule keeps running with the recorded roles. To stop the rule from using those roles, rotate the rule's API key as a different user.

For example, you create a rule while you have the logs-reader custom role, which can read logs-*. Later, you edit the rule's query to include metrics-*. If an administrator adds metrics-* to logs-reader, the rule can query metrics-* on its next run. If the administrator gives you a separate metrics-reader role instead, the rule can't query metrics-* until you rotate its API key.

A rule's Elasticsearch API key records a snapshot of the key owner's privileges when Kibana creates the key. The snapshot doesn't change after that, so later role changes don't affect the rule.

The following table shows how common role changes affect the rule and what to do:

Change Effect on the rule What to do
An administrator gives the key owner more privileges by editing a role or assigning a new one The rule doesn't get the new privileges. Rotate the rule's API key as a user who has them.
An administrator takes privileges away from the key owner by editing a role, deleting a role, or removing a role assignment The rule keeps running with the privileges in the snapshot. To remove that access from the rule, rotate the rule's API key as a user who has only the access the rule needs.

For example, you create a rule while your role can read logs-*. Later, an administrator adds metrics-* to that role, and you edit the rule's query to include metrics-*. The rule still can't query metrics-*, because its key keeps the privileges you had when Kibana created the key. After you rotate the rule's API key, the rule can query both.

Authorizing a workflow run happens in three steps, and each step uses a different credential:

  1. The action policy checks alerts against its match conditions. This step runs as an internal system process and doesn't use a stored credential.
  2. Once a match is found, the policy schedules the workflow using its own stored API key, captured from the user who last saved the policy.
  3. The workflow runs its steps with that same policy key, so the steps can do only what the key's privileges allow. Refer to How steps use the API key for how a key applies across a workflow's steps.

The following authorization errors can cause a rule to fail or prevent an action policy from invoking a workflow. If a workflow produces authorization errors, refer to Workflow authorization.

Error type Cause Where it appears How to resolve it
Insufficient privileges The API key doesn't have the privileges required to query the rule's target data. Rule execution history shows the run as failed. Rotate the rule's API key as a user who has the required index privileges, or have that user disable the rule and enable it again. Saving the rule doesn't replace its key.
Stale or not valid API key The stored key is no longer valid, for example because an administrator deleted it. An API key error in rule execution history. Rotate the rule's API key, or disable the rule and enable it again. Saving the rule doesn't replace its key.
Action policy's API key is missing or not valid The action policy has no stored API key (missing_api_key), or its stored key was deleted or changed (schedule_error). The policy can't schedule the workflow, so the workflow doesn't run. The Action policies tab of the execution history shows the run as Failed, with the failure reason. Save the action policy again to refresh its stored API key.
Action policy's API key lacks the privileges the workflow needs The action policy schedules the workflow, but its API key doesn't have the privileges the workflow's steps need, so the steps fail. The workflow run fails at the affected steps. To confirm which credentials a run used, refer to Workflow authorization. Save the action policy as a user who has the privileges the workflow needs, or update that user's role and save again.