From 706e0b00ec48db0dc8b50b998b01d65e81d9fc10 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 7 Nov 2025 17:37:21 +0100 Subject: [PATCH 1/4] =?UTF-8?q?[Agent=20Builder]=C2=A0Add=20page=20about?= =?UTF-8?q?=20permissions=20and=20access=20control?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- solutions/search/agent-builder/get-started.md | 4 + solutions/search/agent-builder/permissions.md | 96 +++++++++++++++++++ solutions/search/elastic-agent-builder.md | 6 ++ solutions/toc.yml | 1 + 4 files changed, 107 insertions(+) create mode 100644 solutions/search/agent-builder/permissions.md diff --git a/solutions/search/agent-builder/get-started.md b/solutions/search/agent-builder/get-started.md index db1e712a7d..3e5c393661 100644 --- a/solutions/search/agent-builder/get-started.md +++ b/solutions/search/agent-builder/get-started.md @@ -52,6 +52,10 @@ Find **Agents** in the navigation menu to begin using the feature, or search for :::: +:::{note} +To learn about required privileges for {{agent-builder}}, refer to [Permissions and access control](permissions.md). +::: + ::::: ::::{step} Ingest some data diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md new file mode 100644 index 0000000000..3e9660d0d0 --- /dev/null +++ b/solutions/search/agent-builder/permissions.md @@ -0,0 +1,96 @@ +--- +applies_to: + stack: preview 9.2 + serverless: + elasticsearch: preview + observability: unavailable + security: unavailable +navigation_title: "Permissions & access control" +--- + + +# Permissions and access control in {{agent-builder}} + +Use this page to learn how to configure security roles and API keys for Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query. + +Agent Builder requires privileges at three levels: + +- [{{kib}} feature access](#kib-privileges) +- [{{es}} cluster access](#es-cluster-privileges) +- [{{es}} index access](#es-index-privileges) + +### {{kib}} privileges + +Agent Builder uses two {{kib}} privileges within the `agentBuilder` feature: + +- `read_onechat`: Required to use agents, send chat messages, view tools, and access conversations. Maps to the "Read" feature privilege. +- `manage_onechat`: Required to create, update, or delete custom agents and tools. Maps to the "All" feature privilege along with `read_onechat`. + +Learn more about [{{kib}} privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-kibana). + +### {{es}} cluster privileges + +Agent Builder requires cluster-level privileges for AI-powered query generation: + +- `monitor_inference`: Required for agents to use AI-powered tools. The built-in tools `search` and `generate_esql`, as well as [index search tools](tools/index-search-tools.md), call the {{es}} Inference API to generate queries from natural language. + +Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster). + +### {{es}} index privileges + +Tools execute queries against {{es}} indices as the current user. Required privileges depend on which indices the tools access: + +- `read`: Required for tools that query data, including `execute_esql`, `search`, `get_document_by_id`, and [{{esql}} tools](tools/esql-tools.md) +- `view_index_metadata`: Required for tools that inspect index structure, including `list_indices`, `get_index_mapping`, and `index_explorer` + +Learn more about [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). + +### Granting access with roles + +[Roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) are {{es}} security constructs that bundle together {{kib}} feature privileges and {{es}} privileges. To grant users access to Agent Builder, create a role that includes the required privileges. + +Example role for users who need full Agent Builder access: + +```json +POST /_security/role/agent-builder-full +{ + "cluster": ["monitor_inference"], + "indices": [ + { + "names": ["logs-*", "metrics-*"], + "privileges": ["read", "view_index_metadata"] + } + ], + "applications": [ + { + "application": "kibana-.kibana", + "privileges": ["feature_agentBuilder.all"], + "resources": ["space:default"] + } + ] +} +``` + +:::{tip} +For read-only access, use `feature_agentBuilder.read` instead of `feature_agentBuilder.all`. +::: + +### API keys for programmatic access + +When using the Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges. + +Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the {{kib}} API layer rather than through the UI. + +See these pages for API key configuration examples: +- [MCP server](mcp-server.md#api-key-application-privileges) +- [{{kib}} API](kibana-api.md) + +Learn more about [API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md). + +### Spaces + +Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom agents, and custom tools are scoped to the current Space. + +When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. + +Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md). \ No newline at end of file diff --git a/solutions/search/elastic-agent-builder.md b/solutions/search/elastic-agent-builder.md index b6f74ee423..5b6c0915fa 100644 --- a/solutions/search/elastic-agent-builder.md +++ b/solutions/search/elastic-agent-builder.md @@ -66,6 +66,12 @@ These interfaces enable you to build integrations with other applications and ex [**Learn more about programmatic access**](agent-builder/programmatic-access.md) +## Permissions and access control + +Configure security roles and API keys to control who can use agents, which tools they can access, and what data they can query. + +[**Learn more about permissions and access control**](agent-builder/permissions.md) + ## Limitations and known issues {{agent-builder}} is in technical preview. diff --git a/solutions/toc.yml b/solutions/toc.yml index 2a824dabd3..5aff742331 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -77,6 +77,7 @@ toc: - file: search/agent-builder/kibana-api.md - file: search/agent-builder/a2a-server.md - file: search/agent-builder/mcp-server.md + - file: search/agent-builder/permissions.md - file: search/agent-builder/limitations-known-issues.md - file: search/rag.md children: From 683b1e7cca1c7f575d7869e436a7382d8686a65c Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 7 Nov 2025 17:42:42 +0100 Subject: [PATCH 2/4] fix link --- solutions/search/agent-builder/permissions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 3e9660d0d0..e4ad96b7c8 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -26,7 +26,7 @@ Agent Builder uses two {{kib}} privileges within the `agentBuilder` feature: - `read_onechat`: Required to use agents, send chat messages, view tools, and access conversations. Maps to the "Read" feature privilege. - `manage_onechat`: Required to create, update, or delete custom agents and tools. Maps to the "All" feature privilege along with `read_onechat`. -Learn more about [{{kib}} privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-kibana). +Learn more about [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). ### {{es}} cluster privileges @@ -81,7 +81,7 @@ When using the Agent Builder APIs programmatically, authenticate with an API key Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the {{kib}} API layer rather than through the UI. -See these pages for API key configuration examples: +Refer to these pages for API key configuration examples: - [MCP server](mcp-server.md#api-key-application-privileges) - [{{kib}} API](kibana-api.md) From 99d633e0a6b18c335e8fda55882caf7f09371e85 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Sat, 8 Nov 2025 12:34:03 +0100 Subject: [PATCH 3/4] Clarify spaces URLs, add known issue for copy button - Document space-aware URL format for MCP server and APIs - Add known issue: copy button doesn't include space name in URL --- .../search/agent-builder/limitations-known-issues.md | 10 +++++++++- solutions/search/agent-builder/mcp-server.md | 7 +++++++ solutions/search/agent-builder/permissions.md | 6 ++++++ solutions/search/agent-builder/tools.md | 4 ++++ 4 files changed, 26 insertions(+), 1 deletion(-) diff --git a/solutions/search/agent-builder/limitations-known-issues.md b/solutions/search/agent-builder/limitations-known-issues.md index 52f41bec7e..1e15a4d6d2 100644 --- a/solutions/search/agent-builder/limitations-known-issues.md +++ b/solutions/search/agent-builder/limitations-known-issues.md @@ -67,4 +67,12 @@ This results in parsing errors like this: ] ``` - +### MCP server URL copy button does not include space name + +When using the **Copy your MCP server URL** button in the Tools UI from a custom {{kib}} Space, the copied URL does not include the space name in the path. + +**Workaround:** Manually add `/s/` to the URL after your deployment URL. For example: `https:///s//api/agent_builder/mcp` + +For more information about {{agent-builder}} and Spaces, refer to [Permissions and access control](permissions.md#spaces). + + diff --git a/solutions/search/agent-builder/mcp-server.md b/solutions/search/agent-builder/mcp-server.md index b486d58d91..fbe9011e0f 100644 --- a/solutions/search/agent-builder/mcp-server.md +++ b/solutions/search/agent-builder/mcp-server.md @@ -19,6 +19,13 @@ The MCP server is available at: ``` {KIBANA_URL}/api/agent_builder/mcp ``` + +When using a custom {{kib}} Space, include the space name in the URL: + +``` +{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp +``` + :::{tip} You can copy your MCP server URL directly in the Tools GUI. Refer to [](tools.md#copy-your-mcp-server-url). ::: diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index e4ad96b7c8..425d2b582c 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -93,4 +93,10 @@ Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom ag When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. +:::{important} +When accessing Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...` + +The default space uses the standard URL format without `/s/`. +::: + Learn more about [{{kib}} Spaces](/deploy-manage/manage-spaces.md). \ No newline at end of file diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 6075aa3e8c..6445e199a3 100644 --- a/solutions/search/agent-builder/tools.md +++ b/solutions/search/agent-builder/tools.md @@ -208,4 +208,8 @@ The **Tools** UI provides a **Copy your MCP server URL** button for easy access. :width: 250px ::: +:::{important} +If you're using a custom {{kib}} Space, the copied URL will not include the space name. You must manually add `/s/` to the URL path. For example: `https:///s//api/agent_builder/mcp` +::: + For detailed MCP server configuration, refer to [MCP server](mcp-server.md). From c0d6a32bd2e325d968569bc66ea9d4bdebc96067 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 10 Nov 2025 09:59:45 +0100 Subject: [PATCH 4/4] add another link to MCP copy URL --- solutions/search/agent-builder/permissions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/solutions/search/agent-builder/permissions.md b/solutions/search/agent-builder/permissions.md index 425d2b582c..50090226b4 100644 --- a/solutions/search/agent-builder/permissions.md +++ b/solutions/search/agent-builder/permissions.md @@ -93,6 +93,8 @@ Agent Builder respects {{kib}} Spaces when enabled. All conversations, custom ag When configuring roles or API keys, specify the Space in the application privileges resources (e.g., `"resources": ["space:production"]`). Users and API keys cannot access resources in other Spaces. +Learn how to [Copy your MCP server URL](tools.md#copy-your-mcp-server-url). + :::{important} When accessing Agent Builder APIs or the MCP server from a custom Space, include the space name in the URL path: `https:///s//api/agent_builder/...`