Create and manage service accounts in Kibana

Create user-managed service accounts and assign roles to control programmatic access to Elasticsearch and Kibana APIs. Accounts created in Kibana are ready to use with applications such as Workflows, and Kibana automatically manages the credentials needed to run workloads as those accounts.

Some service account capabilities differ between Elastic Cloud Serverless and other deployment types. This guide uses Elastic Stack deployments to refer to Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed deployments.

Note

On Serverless, user-managed service accounts can only be used within Kibana applications. For programmatic access from external applications, use API keys.

You can also create service accounts for external applications through the Elasticsearch API, although accounts created this way can't be assigned to workloads in Kibana applications.

Before you create or manage service accounts, check these requirements:

  • Sign in to Kibana as a user with the manage_security cluster privilege. Without it, the Service accounts page isn't available.
  • Set xpack.encryptedSavedObjects.encryptionKey in kibana.yml. Kibana uses this key to encrypt the stored credential.
  • On Elastic Stack deployments, make sure service accounts are enabled in Kibana. They're enabled by default. If they've been turned off, set xpack.security.serviceAccounts.enabled to true before continuing.

Create a service account with the roles your workloads need:

  1. Find Service accounts in the navigation menu or use the global search field.

  2. Click Create account.

  3. In the Name field, enter a unique name of up to 128 characters. The name must start with a letter or number and can contain letters, numbers, hyphens, and underscores.

  4. Optional: In the Description field, describe what the account is used for.

  5. Under Set privileges, select one or more predefined or custom roles that grant the privileges the account needs. To create a role, click Create new role.

    For details on predefined roles and how to create custom roles, refer to:

  6. Review the selected roles, and click Create account.

  7. Confirm that the account appears in the Service accounts table with the roles you selected. On Elastic Stack deployments, the account uses the principal kibana/<name>.

Your service account is now ready to use in Kibana applications such as Workflows. Kibana manages the credential for you. You don't need to copy a secret, and no token is displayed.

To use the account from an external API client, create a separate named service token.

A service account can have up to 50 roles. Its privileges come from its assigned roles and cannot exceed the access its creator had when the account was created.

Roles reserved for internal use by Kibana Universal Alerting aren't available in the role picker.

When a workload uses cross-project search, its service account's predefined roles apply across linked projects. For a custom role to grant access to a linked project, that project must define a role with the same name. Custom roles aren't copied between projects.

The Service accounts table shows each account's name, description, roles, creator, and number of bound workloads. A Disabled badge identifies accounts that can't authenticate. Use the Role filter to find accounts assigned to specific roles.

When an account has bound workloads, click View in the Workloads column to review them.

Accounts created directly through the Elasticsearch API also appear in the table, but don't have associated Kibana workloads.

You can't update service accounts in the Kibana UI. On Serverless, to change an account's assigned roles or description, delete the account and create a new one. On Elastic Stack deployments, you can update accounts through the Elasticsearch API.

Tip

To change a service account's privileges, you can edit a role already assigned to it without changing the account's role assignments. Changes to a role also affect other users and service accounts assigned that role.

Use the create or replace user-managed service account API to update an account's roles or description, or to deactivate it by setting enabled to false.

The PUT request replaces the complete account definition. Send the full definition, including every role, the description, and the enabled value you want to preserve. A role left out of the roles list is no longer assigned, and an omitted description is cleared. If you omit enabled, it defaults to true. The roles field itself is required.

For example, this request deactivates an account by sending its full definition with enabled set to false:

				PUT /_security/service/kibana/workflow-runner
					{
  "roles": [ "workflow_runner" ],
  "description": "Runs incident response workflows",
  "enabled": false
}

Setting enabled: false prevents authentication with the account's service tokens without deleting the account. It doesn't invalidate short-lived access tokens already issued to run workloads as the account. API keys already issued to the account also remain valid.

To reactivate the account, send the complete definition again with enabled set to true.

Workflows assigned to an account that has enabled: false fail the next time they run. They don't fall back to the user who starts or edits the workflow.

Deleting a service account is permanent. On Elastic Stack deployments, if you only need to temporarily prevent the account from authenticating, deactivate it instead.

To delete a service account:

  1. On the Service accounts page, find the account.
  2. From the Actions column, click Delete.
  3. Review the confirmation:
    • If no workloads are bound, click Delete account.
    • If workloads are bound, review the list. To delete the account without removing the bindings, click Force delete account.

If you force delete an account, workloads assigned to it fail on their next run. To restore access, assign each affected workload a valid service account. This reassignment is required even if you recreate the deleted account with the same name. For Workflows, assign a service account to each affected workflow.

Deleting an account stops new tokens from being issued immediately. Tokens already issued remain valid until they expire, which takes a few minutes at most.

Deleting an account through Kibana attempts to remove every service token, including the credential it stores for workloads and tokens created outside Kibana. It also attempts to invalidate any short-lived access tokens used to run workloads as the account. If any credential cleanup fails, Kibana completes the deletion and reports a warning.

A service token left behind after deletion can't authenticate, but it prevents you from creating another account with the same name until you delete the token. If you delete an account directly through the Elasticsearch API, short-lived access tokens already issued to the account remain valid until they expire, 20 minutes after issuance by default.

Important

API keys owned by the account aren't invalidated when you delete the account. Rules and tasks that obtained an API key while authenticated as the account can continue to run with that key. To revoke this access, invalidate the API keys explicitly.

Use these guides to work with service accounts and learn more about their credentials: