Document user-managed service accounts and workflow execution by eedugon · Pull Request #8921 · elastic/docs-content

eedugon · 2026-10-20T12:54:41Z

Summary (9.6 feature, DO NOT MERGE until release date)

The service accounts documentation currently describes only built-in identities, while Workflows authorization assumes execution as a user. This draft documents user-managed service accounts for Elastic Stack 9.6 on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed deployments, with Kibana as the starting point for account creation.

Related to elastic/docs-content-internal#1733. The scope follows the Tier 1 guidance in Larry's detailed implementation notes. Serverless availability remains marked as unavailable, with follow-up notes for documenting its differences when enabled.

Coverage

Extend the service accounts overview to distinguish built-in and user-managed accounts, explain principals and roles, and cover service token creation, authentication, identity verification, and audit attribution.
Add a Kibana management guide covering creation, account review, updates and deactivation through the Elasticsearch API, and deletion. Explain credential ownership, complete PUT replacement semantics, and the separate revocation of API keys owned by an account.
Add a guide for creating an additional service token and authenticating requests to Kibana APIs as a user-managed account.
Add a Workflows guide for assigning an account with settings.run_as, verifying execution identity, testing saved workflows, handling identity and permission failures, and removing assignments.
Update Workflows authorization, permissions, triggers, step documentation, navigation, and authentication cross-links to account for the new execution model while retaining the existing user-based behavior.

Review

Major updates are in the following docs:

Service accounts + 2 new child-docs
Workflow authorization updates
Run a workflow as a service account (new doc)

Draft review points

Workflows permissions: the current Kibana code requires manage_security to edit or delete an already-bound workflow as well as to change its assignment. Larry's notes describe the requirement as binding-only. The draft follows the code and includes an internal release-check comment; confirm the intended 9.6 behavior and update the related pages together if needed.
Recheck the account creation and role-selection UI after elastic/kibana#296889 lands.
Companion reference work remains in the product repositories: Kibana service account settings, audit event lifecycle labels, and the query service accounts API link when available. Internal follow-up comments identify these items.

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

OpenAI Codex assisted with drafting, product-source research, editing, and validation. The documentation was refined iteratively with the author. SME review is still needed for the permissions discrepancy and the release-dependent UI details listed above.

Closes elastic/docs-content-internal#1733

AI-Assisted: OpenAI Codex

github-actions · 2026-10-20T12:55:18Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

github-actions · 2026-10-20T12:57:19Z

🔍 Preview links for changed docs

Elastic Docs Style Checker (Vale)

Summary: 1 warning, 1 suggestion found

⚠️ Warnings (1): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
explore-analyze/workflows/authorization.md	70	Elastic.Spelling	'auditability' is a possible misspelling.

💡 Suggestions (1): Optional style improvements. Apply when helpful.

File	Line	Rule	Message
explore-analyze/workflows/steps/kibana.md	22	Elastic.Repetition	"to" is repeated.

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

AI-Assisted: OpenAI Codex

talboren · 2026-10-21T09:19:46Z


+:::{note}
+:applies_to: {"stack": "ga 9.6+", "serverless": "unavailable"}
+For a workflow bound to a service account, **Triggered by** identifies the user who starts the workflow or last saved it, depending on the trigger. **Run as** identifies the service account used for authorization. Refer to [Run a workflow as a service account](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md).


also not sure about this but @shahargl probably knows best - i think triggered by will have the SA shown in triggered by..

I've updated it after further reviewing of the code. I think you are right, in certain cases (depending on the type of trigger and the identity used to initiate the run), the triggered by could identify a SA (it doesn't need to be the same SA shown in run_as).

For workflows assigned to a service account, Triggered by shows the identity associated with the start of the run, which can be a user or a service account. Run as shows the assigned service account used for authorization.

But of course if @shahargl is able to confirm it, that would be great.

shainaraskas

did a quick review of the core service account docs. will keep going tomorrow

shainaraskas

last major page. more tomorrow 🐌

AI-Assisted: Codex

bmorelli25

⛷️ OK 👍

eedugon · 2026-11-06T08:59:51Z

-**Q: How can I create {{serverless-full}} service accounts?**  
-A: Create API keys for service accounts in your {{serverless-short}} projects. You can create them in {{kib}}, with the {{es}} API, or as code with Terraform. Refer to [](/deploy-manage/api-keys/serverless-project-api-keys.md) for details.
+**Q: How can I create {{serverless-full}} service accounts?**<br>
+A: You can [create user-managed service accounts in {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/manage-service-accounts-in-kibana.md) for use within {{kib}} applications, such as [Workflows](/explore-analyze/workflows.md). For programmatic access from external applications, use [API keys](/deploy-manage/api-keys.md).


@talboren : I've updated the PR to show serverless availability.
It would be great to get a final review if possible.

AI-Assisted: Codex

Preserve service account execution identities and the expanded trigger documentation from main. AI-Assisted: Codex

shainaraskas

still wip on reviewing the smaller changes on other pages but here are the main pages

shainaraskas · 2026-11-06T16:29:34Z

+
+{applies_to}`serverless: unavailable` To use the account from an external API client, [create a separate named service token](authenticate-kibana-api-with-service-account.md#create-service-account-api-token).
+
+### Roles and privileges in {{serverless-short}} [service-account-serverless-roles]


could bump this to an h2 as it's important context not limited to the creation flow

shainaraskas · 2026-11-06T17:16:14Z

+### Service accounts in {{serverless-short}} [service-accounts-serverless]
+```{applies_to}
+serverless: ga
+```
+
+{{serverless-short}} uses the same [built-in service accounts](#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 {{kib}}. Their identifiers don't use the `<namespace>/<service>` principal format of {{stack}} accounts.
+
+You can assign a user-managed account to a workflow, and {{kib}} 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 {{es}} service account APIs. The service token instructions on this page apply to {{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 {{kib}}](manage-service-accounts-in-kibana.md).


most of this is duplicative with the rest of the page. it also puts tiny serverless details in a dedicated section when they would be more helpful next to their stack counterparts. by paragraph:

the structure of the page implies that built in service accounts are avail for serverless already (we could clarify about management in the built-in service acconts section)

generated identifier is useful but maybe could just be paired with the kibana namespace info above: "In {{stack}}, accounts created in {{kib}} use the kibana namespace, and their principals have the form kibana/<name>."

we explain this where we explain user-managed service accounts above

we explain this where we explain creation on the child page. prob not necessary for this parent

section reworked! thanks for the proposal.

shainaraskas · 2026-11-06T17:20:07Z

+The `settings.run_as` field specifies the ID of the account that runs the workflow. On {{stack}} deployments, this is the account's principal, such as `kibana/incident-response`. On {{serverless-short}}, it is a generated identifier independent of the account's name.

-You can assign an existing account or create one without leaving the workflow editor. In both cases, the account must be [created in {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/manage-service-accounts-in-kibana.md) and have the roles required by the workflow steps. Accounts created directly through the {{es}} API can't be used for workflow execution, even if they use the `kibana` namespace.
+You can assign an existing account or create one without leaving the workflow editor. In both cases, the account must be [created in {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/manage-service-accounts-in-kibana.md) and have the privileges required by the workflow steps.


I'm confused - it says you can create this without leaving the editor, but then says the account must be created (which implies pre-creation)

shainaraskas · 2026-11-06T17:29:50Z

+When you [assign a service account](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md) with `settings.run_as`, every run uses that account's privileges. The trigger type and the user who last saved or started the workflow don't change its privileges.

-The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. {{es}} resolves the account's roles whenever it authenticates, so changes to an assigned role apply to later credential requests without saving the workflow again.
+The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. Changes to an assigned role affect the account's privileges without saving the workflow again.


perhaps? "affect" is a little confusing

Suggested change

The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. Changes to an assigned role affect the account's privileges without saving the workflow again.

The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. Edits to an assigned role update the account's privileges. You don't need to save the workflow again.

legrego · 2026-11-06T17:16:25Z

+serverless: unavailable
+```

 A service account token, or service token, is a unique string that a service uses to authenticate with {{es}}. 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.


A service account token, or service token, is a unique string that a service uses to authenticate with {{es}}.

We state above (correctly) that these tokens can also authenticate to Kibana. Is it confusing that this only says {{es}}?

For a given service account, each token must have a unique name.

This feels out of place in a section talking about tokens. I'd remove it.

Because tokens include access credentials, they should always be kept secret by whichever client is using them.

pedantic nit-picking: The tokens are credentials, they don't include credentials.

changes implemented, thanks!

legrego · 2026-11-06T17:20:22Z

+You can create a service token using either:

-We recommend that you create service tokens via the REST API rather than the CLI. The API stores service tokens within the `.security` index which means that the tokens are available for authentication on all nodes, and will be backed up within cluster snapshots. The use of the CLI is intended for cases where there is an external orchestration process (such as [{{ece}}](/deploy-manage/deploy/cloud-enterprise.md) or [{{eck}}](/deploy-manage/deploy/cloud-on-k8s.md)) that will manage the creation and distribution of the `service_tokens` file.
+* The [create service account token API]({{es-apis}}operation/operation-security-create-service-token) (recommended). The API stores the token in the `.security` index and returns the bearer token in the HTTP response. Tokens are available for authentication on all nodes and are included in cluster snapshots.


The API is only viable if you're not going to use them for Kibana workloads (such as Workflows). If the Service Account is to be used for Kibana workloads, then it must be created within Kibana. Otherwise Kibana won't have the opportunity to create its own managed token.

edit: I see you make this distinction on the child Manage service accounts page.

legrego · 2026-11-06T17:20:39Z


-* The [create service account token API]({{es-apis}}operation/operation-security-create-service-token), which saves the new service token in the `.security` index and returns the bearer token in the HTTP response.
-* Self-managed and {{eck}} deployments only: The [elasticsearch-service-tokens](elasticsearch://reference/elasticsearch/command-line-tools/service-tokens-command.md) CLI tool, which saves the new service token in the `$ES_HOME/config/service_tokens` file and outputs the bearer token to your terminal
+You can create a service token using either:


we don't mention the Kibana UI in this list

It was on purpose, as Kibana UI cannot really be used to create service tokens more than the Fleet (elastic/fleet) service token. Did you mean that?

Adding it just in case.

shainaraskas

couple higher sev ones in here like the malformed applies tag + the kibana page-level tag

otherwise good job reconciling two similar but not same experiences!

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Co-authored-by: Larry Gregory <lgregorydev@gmail.com>

…tic#9168) ## Summary In Stack 9.6 and later, a user-managed service account can call the Agent Builder APIs with a service token, using its own identity and privileges. Serverless can't create these accounts, so every new section is scoped `stack: ga 9.6+` and `serverless: unavailable`. Closes elastic/docs-content-internal#2137. ## What changed | Page | Change | |---|---| | `permissions.md` | New **Service accounts** section under **Configure access**, covering authentication and required privileges. New **Service accounts in conversations** section under **Conversation access control**, covering ownership, public conversations, and adding the account as a member. **The member role** links to it. | | `kibana-api.md` | New **Chat as a service account** example. The **Update conversation access control** example now covers service account member IDs. | | `chat.md` | New **Messages from a service account** subsection, including how a workflow can set `author_name`. **Share a conversation** now notes that service accounts don't appear in the user search, are hidden from the member lists, and count toward the sharing button total. | | `programmatic-access.md` | One line pointing service account clients to `permissions.md`. | ## Dependency How to create a user-managed service account and its token is documented in elastic#8921. `%` comments in `permissions.md` and `kibana-api.md` mark where to link `authenticate-kibana-api-with-service-account.md` after elastic#8921 merges. Until then, the token link points to the existing service accounts page, which covers built-in accounts only.

AI-Assisted: Codex

Document user-managed service accounts and workflow execution

bcaf604

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 13:01

View deployment

Preserve service account focus in Serverless FAQ

d227313

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 15:40

View deployment

Clarify service account API authentication in Kibana

a681fa5

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 15:59

View deployment

Clarify service account implications of workflow editing

58e17e5

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 16:06

View deployment

Clarify workflow execution identity and service account guidance

104d7e3

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 16:28

View deployment

Clarify authorization for alert-triggered workflows

0979876

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 16:45

View deployment

Align authorization guidance across workflow triggers

4b46564

AI-Assisted: OpenAI Codex

github-actions Bot deployed to docs-preview October 20, 2026 16:56

View deployment

eedugon added the 9.6 label Oct 20, 2026

eedugon requested a review from legrego October 21, 2026 08:44

eedugon assigned alxchalkias Oct 21, 2026

eedugon marked this pull request as ready for review October 21, 2026 08:45

eedugon requested review from a team as code owners October 21, 2026 08:45

eedugon requested a review from alxchalkias October 21, 2026 08:45

eedugon unassigned alxchalkias Oct 21, 2026

talboren reviewed Oct 21, 2026

View reviewed changes

Comment thread deploy-manage/deploy/elastic-cloud/serverless-faq.md Resolved

talboren reviewed Oct 21, 2026

View reviewed changes

Comment thread explore-analyze/workflows/authoring-techniques/manage-workflows.md Resolved

talboren reviewed Oct 21, 2026

View reviewed changes

shainaraskas reviewed Oct 21, 2026

View reviewed changes

shainaraskas reviewed Oct 22, 2026

View reviewed changes

github-actions Bot deployed to docs-preview November 5, 2026 17:05

View deployment

eedugon added 4 commits November 5, 2026 18:07

Inherit Serverless scope for the service token note

58c3ef4

AI-Assisted: Codex

Inherit Stack version scope for the service account API link

1f69b55

AI-Assisted: Codex

Clarify service tokens and Serverless API authentication

376e51f

AI-Assisted: Codex

Remove redundant API caveat from the workflow service account guide

2417918

AI-Assisted: Codex

bmorelli25 approved these changes Nov 5, 2026

View reviewed changes

eedugon requested review from legrego, shainaraskas and talboren November 6, 2026 06:54

eedugon commented Nov 6, 2026

View reviewed changes

Link Serverless service account FAQ to project API keys

1a5dba7

AI-Assisted: Codex

github-actions Bot deployed to docs-preview November 6, 2026 11:10

View deployment

alxchalkias approved these changes Nov 6, 2026

View reviewed changes

Merge main into service_accounts_user_managed

2bb79f0

Preserve service account execution identities and the expanded trigger documentation from main. AI-Assisted: Codex

github-actions Bot deployed to docs-preview November 6, 2026 16:47

View deployment

shainaraskas reviewed Nov 6, 2026

View reviewed changes

legrego reviewed Nov 6, 2026

View reviewed changes

shainaraskas approved these changes Nov 6, 2026

View reviewed changes

legrego mentioned this pull request Nov 7, 2026

Support user-managed service account authentication on Elasticsearch 9.6+ legrego/homeassistant-elasticsearch#615

Open

9 tasks

Apply suggestions from code review

71ec621

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Co-authored-by: Larry Gregory <lgregorydev@gmail.com>

github-actions Bot deployed to docs-preview November 9, 2026 14:24

View deployment

eedugon added 2 commits November 9, 2026 18:00

reviewing progress

3177cfc

Consolidate Serverless service account guidance

37039bc

AI-Assisted: Codex

github-actions Bot deployed to docs-preview November 9, 2026 17:08

View deployment

eedugon added 2 commits November 9, 2026 18:09

Clarify service account token credentials and authentication

613d0b3

AI-Assisted: Codex

Refine service token API authentication and secrecy guidance

2e6baec

AI-Assisted: Codex

github-actions Bot deployed to docs-preview November 9, 2026 17:23

View deployment

Clarify Kibana account creation and Fleet service token generation

679a6b6

AI-Assisted: Codex

github-actions Bot deployed to docs-preview November 9, 2026 17:36

View deployment


		{applies_to}`serverless: unavailable` To use the account from an external API client, [create a separate named service token](authenticate-kibana-api-with-service-account.md#create-service-account-api-token).

		### Roles and privileges in {{serverless-short}} [service-account-serverless-roles]

	The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. Changes to an assigned role affect the account's privileges without saving the workflow again.
	The workflow stores a reference to the account. When a run starts, {{kib}} obtains a short-lived credential and renews it as needed. Edits to an assigned role update the account's privileges. You don't need to save the workflow again.

Conversation

eedugon commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary (9.6 feature, DO NOT MERGE until release date)

Coverage

Review

Draft review points

Generative AI disclosure

Uh oh!

github-actions Bot commented Oct 20, 2026

Elastic Docs AI PR menu

Uh oh!

github-actions Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Elastic Docs Style Checker (Vale)

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eedugon Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmorelli25 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

eedugon commented Oct 20, 2026 •

edited

Loading

github-actions Bot commented Oct 20, 2026 •

edited

Loading

github-actions Bot commented Oct 20, 2026 •

edited

Loading

eedugon Oct 29, 2026 •

edited

Loading