Document user-managed service accounts and workflow execution

deploy-manage/deploy/elastic-cloud/serverless-faq.md

@@ -32,8 +32,8 @@ User-initiated data recovery is anticipated in a future release. You can follow
 
 ## Security, compliance, and access
 
-**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/serverless-project-api-keys.md).
 
 **Q: Can I configure {{es}} authentication realms (for example, native realm) in {{serverless-short}} projects?**  
 A: No. {{serverless-short}} uses a different authentication model and does not support [{{es}} authentication realms](/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md). Project-level access is handled through [Serverless project API keys](/deploy-manage/api-keys/serverless-project-api-keys.md), and user authentication is managed at the [{{ecloud}} organization level](/deploy-manage/users-roles/cloud-organization.md) (including SAML SSO).

deploy-manage/toc.yml

@@ -625,6 +625,9 @@ toc:
               - file: users-roles/cluster-or-deployment-auth/anonymous-access.md
               - file: users-roles/cluster-or-deployment-auth/token-based-authentication-services.md
               - file: users-roles/cluster-or-deployment-auth/service-accounts.md
+                children:
+                  - file: users-roles/cluster-or-deployment-auth/manage-service-accounts-in-kibana.md
+                  - file: users-roles/cluster-or-deployment-auth/authenticate-kibana-api-with-service-account.md
               - file: users-roles/cluster-or-deployment-auth/internal-users.md
               - file: users-roles/cluster-or-deployment-auth/operator-privileges.md
                 children:

deploy-manage/users-roles/cloud-organization.md

@@ -24,6 +24,8 @@ You can perform the following tasks to control access to your Cloud organization
 
 You can also control programmatic access to {{ecloud}}, your deployments, and your projects using [API keys](/deploy-manage/api-keys.md).
 
+For workloads that run within {{kib}} applications in {{serverless-short}} projects, you can also use [user-managed service accounts](/deploy-manage/users-roles/cluster-or-deployment-auth/service-accounts.md).
+
 :::{tip}
 If you're using {{ech}}, then you can also manage users and control access [at the deployment level](/deploy-manage/users-roles/cluster-or-deployment-auth.md).
 :::

deploy-manage/users-roles/cluster-or-deployment-auth/authenticate-kibana-api-with-service-account.md

@@ -0,0 +1,72 @@
+---
+navigation_title: Authenticate to Kibana APIs
+applies_to:
+  stack: ga 9.6+
+  serverless: unavailable
+description: Create a service token and use a user-managed service account to authenticate to Kibana APIs.
+products:
+  - id: kibana
+  - id: elasticsearch
+  - id: cloud-hosted
+  - id: cloud-enterprise
+  - id: cloud-kubernetes
+  - id: elastic-stack
+---
+
+# Authenticate to the {{kib}} API with a service account [authenticate-kibana-api-service-account]
+
+Use a service token to authenticate programmatic requests to {{kib}} as a user-managed service account. The account provides a non-human identity whose privileges come from its assigned roles.
+
+Service accounts can't be used with external applications on {{serverless-full}}. For programmatic access from external applications, use [API keys](/deploy-manage/api-keys.md).
+
+## Before you begin [authenticate-kibana-api-service-account-prerequisites]
+
+Before you create a service token, make sure you have the following:
+
+- You need an existing user-managed service account. If you don't have one, [create a service account in {{kib}}](manage-service-accounts-in-kibana.md#create-service-account-kibana).
+- You need the `manage_security` cluster privilege to create a service token for a user-managed account. The `manage_service_account` privilege permits token management only for built-in accounts in the `elastic` namespace.
+
+## Create a service token for your application [create-service-account-api-token]
+
+{{kib}} creates and stores a credential when you create an account in the UI. That credential is used for workload integrations and isn't displayed. For your application, create an additional service token. The following example uses an existing account with the principal `kibana/automation-client`:
+
+1. Use the [create service account token API]({{es-apis}}operation/operation-security-create-service-token) to create a token for the account:
+
+    ```console
+    POST /_security/service/kibana/automation-client/credential/token/production
+    ```
+
+2. Copy the `token.value` from the response and store it securely, such as in a secrets manager. Service tokens don't expire, and you can't retrieve this value again.
+
+## Call a {{kib}} API [call-kibana-api-service-account]
+
+To call the {{kib}} API using the service account identity, send the token with the `Bearer` authentication scheme:
+
+```shell
+curl --request GET "$KIBANA_URL/api/spaces/space" \
+  --header "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN"
+```
+
+
+For requests that change data, also include the headers required by that API, such as `kbn-xsrf`.
+
+## Call an {{es}} API [call-elasticsearch-api-service-account]
+
+You can use the same token to authenticate to {{es}}. For example, verify the account's identity with the authenticate API:
+
+```shell
+curl --request GET "$ELASTICSEARCH_URL/_security/_authenticate" \
+  --header "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN"
+```
+
+## Remove access [remove-service-account-api-access]
+
+Service tokens don't expire. When an application no longer needs access, use the [delete service account token API]({{es-apis}}operation/operation-security-delete-service-token) to delete only its token:
+
+```console
+DELETE /_security/service/kibana/automation-client/credential/token/production
+```
+
+Deleting the token stops requests that use it without affecting the account or its other service tokens.
+
+To prevent new authentications with any of the account's service tokens, [deactivate the account](manage-service-accounts-in-kibana.md#disable-service-account). To permanently remove the identity and its associated credentials, [delete the account in {{kib}}](manage-service-accounts-in-kibana.md#delete-service-account-kibana).

deploy-manage/users-roles/cluster-or-deployment-auth/kibana-authentication.md

@@ -416,6 +416,7 @@ xpack.security.authc.http.schemes: [apikey, bearer, basic, something-custom]
 
 With this configuration, you can send requests to {{kib}} with the `Authorization` header using `ApiKey`, `Bearer`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {{kib}} relays this header to {{es}}, then {{es}} authenticates the request using the credentials in the header.
 
+{applies_to}`{stack: ga 9.6+, serverless: unavailable}` User-managed service accounts provide another option for programmatic access to {{kib}} APIs. Their service tokens use the `Bearer` scheme, but they can't be used to log in to the {{kib}} UI. To create a token and authenticate a request, refer to [Authenticate to the {{kib}} API with a service account](authenticate-kibana-api-with-service-account.md).
 
 ### Embedded content authentication [embedded-content-authentication]
 

deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md

@@ -225,6 +225,13 @@ These privileges control specific actions on workflows. Selecting **All** includ
 | **Update managed workflows** {applies_to}`stack: ga 9.5+` | Edit the workflows that Elastic provides. |
 :::
 
+:::{warning}
+:applies_to: {"stack": "ga 9.6+", "serverless": "ga"}
+When you edit a workflow that runs as a service account, subsequent runs continue to use that account's privileges. Your changes can therefore use privileges you don't personally have. Grant workflow edit access only to users you trust to use those privileges.
+
+Adding, changing, or removing a service account assignment, and editing or deleting a workflow assigned to a service account, also require the `manage_security` cluster privilege. For account assignment instructions and required privileges, refer to [Run a workflow as a service account](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md).
+:::
+
 ## Privileges in the Management group [kibana-privileges-management]
 
 Each of the following privileges controls access to a different feature.

deploy-manage/users-roles/cluster-or-deployment-auth/manage-service-accounts-in-kibana.md

@@ -0,0 +1,142 @@
+---
+navigation_title: Manage service accounts
+applies_to:
+  stack: ga 9.6+
+  serverless: ga
+description: Create, review, take out of service, and delete user-managed service accounts for Kibana workloads.
+products:
+  - id: kibana
+  - id: elasticsearch
+  - id: cloud-serverless
+  - id: cloud-hosted
+  - id: cloud-enterprise
+  - id: cloud-kubernetes
+  - id: elastic-stack
+---
+
+# Create and manage service accounts in {{kib}} [manage-service-accounts-kibana]
+
+Create user-managed service accounts and assign roles to control programmatic access to {{es}} and {{kib}} APIs. Accounts created in {{kib}} are ready to use with {{kib}} applications such as [Workflows](/explore-analyze/workflows.md). On {{stack}} deployments, you can also use them with your own applications by [creating a service token](authenticate-kibana-api-with-service-account.md#create-service-account-api-token).
+
+:::{note}
+:applies_to: serverless: ga
+On {{serverless-short}}, user-managed service accounts can only be used within {{kib}} applications. For programmatic access from external applications, use [API keys](/deploy-manage/api-keys.md).
+:::
+
+{applies_to}`serverless: unavailable` You can also create service accounts for external applications through the [{{es}} API]({{es-apis}}operation/operation-security-put-user-managed-service-account), although accounts created this way can't be assigned to workloads in {{kib}} applications.
+
+## Before you begin [manage-service-accounts-before-you-begin]
+
+Before you create or manage service accounts, check these requirements:
+
+- Sign in to {{kib}} as a user with the `manage_security` cluster privilege. Without it, the **Service accounts** page isn't available.
+- {applies_to}`self: ga` Set [`xpack.encryptedSavedObjects.encryptionKey`](kibana://reference/configuration-reference/security-settings.md#xpack-encryptedsavedobjects-encryptionkey) in `kibana.yml`. {{kib}} uses this key to encrypt the stored credential.
+- On {{stack}} deployments, service accounts must be enabled in {{kib}}. This is the default. If your deployment turns them off, set [`xpack.security.serviceAccounts.enabled`](kibana://reference/configuration-reference/security-settings.md#service-account-settings) to `true` to re-enable them.
+
+## Create a service account [create-service-account-kibana]
+
+Create a service account with the roles your workloads need:
+
+1. Find **Service accounts** in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
+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:
+
+    - {{stack}} deployments: [Built-in roles](elasticsearch://reference/elasticsearch/roles.md) and [role management in {{kib}}](kibana-role-management.md).
+    - {{serverless-short}} projects: [Predefined roles](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles-table) and [custom roles](/deploy-manage/users-roles/serverless-custom-roles.md). Before you assign roles, review the [role limits in {{serverless-short}}](#service-account-serverless-roles).
+
+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 {{stack}} deployments, the account uses the principal `kibana/<name>`.
+
+Your service account is now ready to use in {{kib}} applications such as [Workflows](/explore-analyze/workflows.md). {{kib}} manages the credential for you. You don't need to copy a secret, and no token is displayed.
+
+{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]
+```{applies_to}
+serverless: ga
+```
+
+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.
+
+When a workload uses [cross-project search](/explore-analyze/cross-project-search.md), 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.
+
+
+## Review service accounts [review-service-accounts-kibana]
+
+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.
+
+## Update a service account [update-service-account-kibana]
+
+You can't update service accounts in the {{kib}} UI. On {{serverless-short}}, to change an account's assigned roles or description, [delete the account](#delete-service-account-kibana) and [create a new one](#create-service-account-kibana). On {{stack}} deployments, you can update accounts through the {{es}} 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.
+:::
+
+### Update or deactivate an account through the {{es}} API [disable-service-account]
+```{applies_to}
+serverless: unavailable
+```
+
+Use the [create or replace user-managed service account API]({{es-apis}}operation/operation-security-put-user-managed-service-account) 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`:
+
+```console
+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](token-based-authentication-services.md#token-authentication-access-token) 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](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md#assign-workflow-service-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.
+
+## Delete a service account [delete-service-account-kibana]
+
+Deleting a service account is permanent. On {{stack}} deployments, if you only need to temporarily prevent the account from authenticating, [deactivate it](#disable-service-account) 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](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md#assign-workflow-service-account).
+
+
+### Credentials after deletion in {{stack}} deployments [delete-service-account-stack-credentials]
+```{applies_to}
+serverless: unavailable
+```
+
+Deleting an account through {{kib}} attempts to remove every service token, including the credential it stores for workloads and tokens created outside {{kib}}. It also attempts to invalidate any short-lived access tokens used to run workloads as the account. If any credential cleanup fails, {{kib}} 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.
+
+:::{important}
+API keys owned by the account aren't invalidated when you delete the account. {{rules-ui}} 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]({{es-apis}}operation/operation-security-invalidate-api-key) explicitly.
+:::
+
+## Next steps [manage-service-accounts-next-steps]
+
+Use these guides to work with service accounts and learn more about their credentials:
+
+- [Run a workflow as a service account](/explore-analyze/workflows/authoring-techniques/run-workflow-as-service-account.md).
+- {applies_to}`serverless: unavailable` [Authenticate to the {{kib}} API with a service account](authenticate-kibana-api-with-service-account.md).
+- Learn more about [service account types and credentials](service-accounts.md).