Service accounts

A service account is a non-human identity for a service or workload. Unlike a user, a service account isn't associated with a person and can't log in to the Kibana UI.

Service accounts authenticate with tokens. The account defines the identity and privileges, while the token is a credential for that identity.

Important

Don't use service accounts to authenticate individual users. Service account credentials are for software and workloads, not people.

This page refers to Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed deployments as Elastic Stack deployments. In these environments, Elasticsearch stores and manages user-managed service accounts. In Elastic Cloud Serverless projects, Elastic Cloud manages these accounts at the organization level. These differences affect account identifiers, credentials, and the available management APIs.

Each service account has a unique identifier, called a principal. In Elastic Stack deployments, the principal has the form <namespace>/<service>. The namespace groups related accounts, and the service name must be unique within that namespace.

Service accounts can be built-in, with privileges defined by Elastic, or user-managed, with privileges determined by the roles you assign.

Built-in service accounts are predefined in code, always enabled, and have fixed privileges.

A built-in service account corresponds to a specific service.

The following built-in accounts are available:

elastic/fleet-server
The service account used by the Fleet server to communicate with Elasticsearch.
elastic/kibana
The service account used by Kibana to communicate with Elasticsearch.

The elastic namespace is reserved for built-in accounts.

In Elastic Stack, you can create and delete service tokens for these accounts, but you can't change their predefined privileges.

You create these accounts and assign roles to control their privileges. The accounts belong to the deployment on Elastic Stack or to the Cloud organization on Serverless, rather than to the user who created them. In Elastic Stack, accounts created in Kibana use the kibana namespace, and their principals have the form kibana/<name>.

Use a user-managed service account when your workload needs its own identity to access Elasticsearch or Kibana APIs. Assign the roles required by the workload.

Workflows is the only Kibana application that supports directly assigning a service account as the execution identity of a workload. Kibana manages the credential used for this integration.

Note

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

To manage service accounts and use them in your workloads:

To use service accounts with Kibana Workflows, refer to Run a workflow as a service account.

On Elastic Stack, the Elasticsearch API reference also documents these operations:

Serverless uses the same built-in service accounts, with credentials managed by Elastic.

User-managed accounts have a generated identifier that is independent of the name you enter in Kibana. Their identifiers don't use the <namespace>/<service> principal format of Elastic Stack accounts.

You can assign a user-managed account to a workflow, and Kibana manages the short-lived credentials used to run it. You can't obtain a token for an external application or manage these accounts through the Elasticsearch service account APIs. The service token instructions on this page apply to Elastic Stack.

The account's privileges are limited to those allowed by both its assigned roles and its creator's access at creation time. For details about role limits, cross-project search, and deleting accounts, refer to Create and manage service accounts in Kibana.

A service account token, or service token, is a unique string that a service uses to authenticate with Elasticsearch. For a given service account, each token must have a unique name. Because tokens include access credentials, they should always be kept secret by whichever client is using them.

For example, Fleet server uses a service token to authenticate with Elasticsearch and manage its own API keys. You can create multiple service tokens for the same service account. This lets multiple instances of a service use the same identity without sharing credentials.

Note

When you create a user-managed service account in Kibana, Kibana creates and stores a service token so applications such as Workflows can run on behalf of the account. This token isn't displayed. To authenticate requests from your own application, create an additional service token with the API.

You can create a service token using either:

Both the API and CLI generate service tokens with a 22-character secret. Elasticsearch requires a secret of at least 10 characters and rejects shorter secrets without checking their value.

Service tokens never expire. You must actively delete them if they are no longer needed.

Service tokens are different from short-lived access tokens, which expire automatically. For an overview of these credential types and API keys, refer to Token-based authentication services.

To authenticate requests to Elasticsearch, include the service token in the Authorization: Bearer header of each request. Service accounts don't support basic authentication.

You can verify a service token, for example, by calling the authenticate API (GET /_security/_authenticate). This API returns information about the authenticated identity, including its principal, assigned roles, and authentication details.

Set ELASTICSEARCH_URL to your deployment's HTTPS endpoint and SERVICE_ACCOUNT_TOKEN to your service token:

curl --request GET "$ELASTICSEARCH_URL/_security/_authenticate" \
  --header "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN"

The following examples show the response for each type of service account:

This example uses the elastic/fleet-server account, which has predefined privileges:

{
  "username": "elastic/fleet-server",
  "roles": [],
  "full_name": "Service account - elastic/fleet-server",
  "email": null,
  "token": {
    "name": "production",
    "type": "_service_account_index"
  },
  "metadata": {
    "_elastic_service_account": true
  },
  "enabled": true,
  "authentication_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "lookup_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "authentication_type": "token"
}

This example uses the kibana/automation-client account with the automation_client role:

{
  "username": "kibana/automation-client",
  "roles": [
    "automation_client"
  ],
  "full_name": "User-managed service account - kibana/automation-client",
  "email": null,
  "token": {
    "name": "production",
    "type": "_service_account_index"
  },
  "metadata": {
    "_user_managed_service_account": true
  },
  "enabled": true,
  "authentication_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "lookup_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "authentication_type": "token"
}

In both responses:

  • username is the principal of the authenticated account.
  • roles lists the assigned role names. Built-in accounts return an empty array because their privileges are predefined.
  • token describes the credential used for the request. Its name is the service token's name, and its type identifies the storage backend: _service_account_index for tokens stored in the .security index, or _service_account_file for file-backed tokens used by built-in accounts.
  • metadata identifies the account type: _elastic_service_account for built-in accounts or _user_managed_service_account for user-managed accounts.
Note

Service accounts are not included in the response of the get users API. To retrieve a service account, use the get service accounts API. Use the get service account credentials API to retrieve all service credentials for a service account.

To authenticate calls to Kibana with a user-managed service account, refer to Authenticate to the Kibana API with a service account.

Kibana audit events record account creation and deletion, changes to workload assignments, and attempts to run a workload as an account. The service_account_assume event identifies the account and workload execution. Events caused by that workload identify the service account as the acting principal.

In Elastic Stack, Elasticsearch audit events also attribute requests that use a service account credential to the account.

On Serverless, configure audit trail log delivery to collect audit logs from your project.