CPS: Refactor auth-related stuff and small style edits

deploy-manage/_snippets/cps-definition.md

@@ -0,0 +1 @@
+With {{cps}} ({{cps-init}}), users in your organization can search across multiple {{serverless-full}} projects at once, instead of searching each project individually. When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all the data from a single place. 

deploy-manage/api-keys/elastic-cloud-api-keys.md

@@ -128,7 +128,7 @@ Using {{ecloud}} keys for project-level API access, rather than [granting keys f
 
 :::{important} 
 :applies_to: serverless: preview
-The [cross-project search feature](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#cps-programmatic-access) requires {{ecloud}} API keys for programmatic access.
+The [cross-project search feature](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access) requires {{ecloud}} API keys for programmatic access.
 :::
 
 When granting Cloud resource access, you can apply a [predefined role](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles-table) or [custom role](/deploy-manage/users-roles/serverless-custom-roles.md) to granularly control access to the specified resources. The selected role controls access to resources in all relevant APIs. 

deploy-manage/api-keys/serverless-project-api-keys.md

@@ -17,7 +17,7 @@ In {{serverless-short}} projects, the following types of API keys exist:
 :::{admonition} Manage {{serverless-short}} project API access using {{ecloud}} API keys
 As an alternative to using {{serverless-short}} project API keys, which are tied to a single project, you can create [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md) that include access to projects' {{es}} and {{kib}} APIs. This allows you to create keys that can interact with multiple projects, and manage API access centrally from the {{ecloud}} console. 
 
-The [cross-project search feature](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#cps-programmatic-access) requires {{ecloud}} API keys for programmatic access.
+The [cross-project search feature](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md##manage-user-and-api-key-access) requires {{ecloud}} API keys for programmatic access.
 :::
 
 To manage API keys in {{kib}}, go to the **API keys** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).

deploy-manage/cross-project-search-config.md

@@ -9,11 +9,12 @@ navigation_title: "Cross-project search"
 
 # Configure {{cps}} [configure-cross-project-search]
 
-With {{cps}} ({{cps-init}}), users in your organization can search across multiple {{serverless-full}} projects at once, instead of searching each project individually. When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all the data from a single place. 
+::::{include} /deploy-manage/_snippets/cps-definition.md
+::::
 
 {{cps-cap}} is the {{serverless-short}} equivalent of [{{ccs}}](/explore-analyze/cross-cluster-search.md), with a few differences and enhancements:
 
-* Setting up cross-project search doesn't require an understanding of your deployment architecture or complex security configurations.
+* Setting up {{cps}} doesn't require an understanding of your deployment architecture or complex security configurations.
 * Permissions stay consistent across projects, and you can always adjust scope and access as needed. 
 * Searches are performed across projects by default, reducing the need to refactor your queries as you link additional projects.
 
@@ -86,7 +87,7 @@ The overview project model is strongly recommended and appropriate for most {{cp
 
 - **Shared data project (N-to-1):** A single project stores data from a shared service (for example, logs). Multiple origin projects link to this central data project. 
 
-    The N-to-1 pattern is often used when several teams need to query shared data independently. The main risk is that linking to a shared data project affects searches, dashboards, and alerts in each origin project. If the shared project is a large, active project, the expanded dataset might cause unexpected behavior. If you're using this pattern, make sure to [manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-access) and consider [CPS scope](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#cps-search-scope).
+    The N-to-1 pattern is often used when several teams need to query shared data independently. The main risk is that linking to a shared data project affects searches, dashboards, and alerts in each origin project. If the shared project is a large, active project, the expanded dataset might cause unexpected behavior. If you're using this pattern, make sure to [manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access) and consider [CPS scope](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#cps-search-scope).
 
 - **Data mesh (N-to-N):** Multiple active projects link directly to each other.
 
@@ -113,7 +114,7 @@ When you link projects for {{cps}}, the expanded dataset can affect existing fea
 
 - **Dashboards and visualizations:** Existing dashboards and visualizations in the origin project will query all linked projects by default. To control this, set the [default {{cps}} scope](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#cps-default-search-scope) for each space, or save explicit project routing on individual dashboard panels.
 
-- **User permissions:** {{cps-cap}} results are filtered by each user's role assignments across projects. Users with different roles will see different results from the same query. Refer to [Manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-access).
+- **User permissions:** {{cps-cap}} results are filtered by each user's role assignments across projects. Users with different roles will see different results from the same query. Refer to [Manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access).
 
 - **{{product.painless}} scripting:** The [{{product.painless}} execute API](/explore-analyze/cross-project-search.md#cps-painless-scripting) does not search across linked projects. It resolves index names against the origin project only. You can target a linked project by prefixing the index with the project alias (for example, `projectAlias:myindex`).
 

deploy-manage/cross-project-search-config/cps-config-access-and-scope.md

@@ -13,30 +13,22 @@ This page explains how user permissions and scope affect {{cps}} ({{cps-init}})
 
 For more details about {{cps-init}} configuration, refer to [](/deploy-manage/cross-project-search-config.md). For information about _using_ {{cps-init}}, refer to [](/explore-analyze/cross-project-search.md).
 
-## Manage user access [manage-user-access]
+## Manage user and API key access
 
-Access to data in linked projects is determined by the [roles](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) assigned to the user in each project. Whether a user queries a project directly or through {{cps}}, the same permissions apply.
-
-When a {{cps}} query reaches a linked project, the system verifies the user's identity and evaluates the roles assigned to that user in the linked project. Users can only access resources if their roles permit. This means {{cps}} results can vary by user, depending on each user's role assignments across projects.
-
-For example, if a user has read access to the `logs` index in Project B but not in Project C, a {{cps}} for `logs` returns documents from Project B and silently excludes Project C.
-
-For additional information, refer to [{{cps-init}} security](/explore-analyze/cross-project-search.md#security).
-
-% TODO ^^ snippetize from E&A
-
-## Manage programmatic access [cps-programmatic-access]
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-security.md
+:::
 
-The same role-based access model applies to programmatic access through API keys. For {{cps}}, you must use [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md), which can authenticate across project boundaries.
+### How access is evaluated
 
-Project-scoped API keys, such as [{{serverless-short}} project API keys](/deploy-manage/api-keys/serverless-project-api-keys.md), cannot search across project boundaries. If a project-scoped API key is used in a {{cps}} context, it silently returns results from the origin project only (no error is returned).
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md
+:::
 
 ## Administrator tasks
 % TODO better heading
 
-- Make sure that users who need to search across linked projects have a [role assigned](/deploy-manage/users-roles.md) on each linked project they need to access. Authorization is evaluated on the linked project, without regard to the origin project.
+- Make sure that users who need to search across linked projects have a [role assigned](/deploy-manage/users-roles.md) on each linked project they need to access, and are granted **Cloud Console, {{es}}, and {{kib}}** access to those projects. Authorization is evaluated on the linked project, without regard to the origin project.
 - If a user reports missing data from a linked project, check their role assignment on that specific linked project first.
-- For programmatic access, make sure the {{ecloud}} API key has the appropriate [roles](/deploy-manage/api-keys/elastic-cloud-api-keys.md#roles) on each project the key needs to access.
+- For programmatic access, make sure the {{ecloud}} API key has the appropriate [roles](/deploy-manage/api-keys/elastic-cloud-api-keys.md#roles) on each project the key needs to access, and is granted **Cloud, {{es}}, and {{kib}} API access** to those projects.
 
 % TODO alerting impacts of user role changes 
 
@@ -66,7 +58,7 @@ The following actions change the scope of {{cps}}es:
 
 - **Administrator actions:** 
   - Setting the [default {{cps}} scope for a space](#cps-default-search-scope)
-  - Adjusting [user permissions](#manage-user-access) using roles or API keys (for example, creating {{ecloud}} API keys that span multiple projects)
+  - Adjusting [user permissions](#manage-user-and-api-key-access) using roles or API keys (for example, creating {{ecloud}} API keys that span multiple projects)
 - **User actions:**
   - Using the [{{cps-init}} scope selector](/explore-analyze/cross-project-search/cross-project-search-manage-scope.md#cps-in-kibana) in the project header
   - Using [qualified search expressions](/explore-analyze/cross-project-search/cross-project-search-search.md#search-expressions)
@@ -101,7 +93,7 @@ Space settings are managed in {{kib}}.
 % (not yet) - **Specific projects:** Select individual linked projects to include in the default scope.
 
 ::::{note}
-The default {{cps}} scope is a space setting, not an access control. Users can still set the scope at the query level. You can also [manage user access](#manage-user-access).
+The default {{cps}} scope is a space setting, not an access control. Users can still set the scope at the query level. You can also [manage user access](#manage-user-and-api-key-access).
 ::::
 
 ## Next steps

deploy-manage/cross-project-search-config/cps-config-link-and-manage.md

@@ -42,7 +42,7 @@ To link projects, use the {{cps}} linking wizard in the {{ecloud}} UI:
 
 1. Select the checkbox for each project you want to link. You can link up to 20 projects to each origin project.
 
-     If a project you expected to link to is missing from the list, it might not meet the [requirements](/deploy-manage/cross-project-search-config.md#cps-compatibility), or you might not have the necessary [permissions](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-access) on the linked project.
+     If a project you expected to link to is missing from the list, it might not meet the [requirements](/deploy-manage/cross-project-search-config.md#cps-compatibility), or you might not have the necessary [permissions](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access) on the linked project.
 
 1. Complete the remaining steps in the wizard to review and save your selections. In the last step, you can click **View API request** to see the equivalent API request for linking to the selected projects.
 

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

@@ -147,7 +147,7 @@ When **Cloud Console, {{es}}, and {{kib}}** access is not granted, roles that ar
 * Several predefined roles that are intended for project users, such as the Security **Tier 1 analyst** role, can view the relevant projects on the {{ecloud}} Console home page, but can't open the project to view their dashboards and visualizations.
 * [Custom roles](/deploy-manage/users-roles/serverless-custom-roles.md) always require **Cloud Console, {{es}}, and {{kib}}** access. Without it, users have only **Viewer** access in the {{ecloud}} Console, and can't log in to the project.
 
-{applies_to}`serverless: preview` If your organization uses [{{cps}}](/deploy-manage/cross-project-search-config.md), the roles assigned to a user determine what data they can access across linked projects. Users can only see data from a linked project if their role on that project grants the necessary privileges. Refer to [Manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-access).
+{applies_to}`serverless: preview` If your organization uses [{{cps}}](/deploy-manage/cross-project-search-config.md), the roles assigned to a user determine what data they can access across linked projects. Users can only see data from a linked project if their role on that project grants the necessary privileges. Refer to [Manage user access](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access).
 
 For details on the permissions granted for each role, refer to the [predefined roles table](#general-assign-user-roles-table).
 

explore-analyze/cross-project-search.md

@@ -9,19 +9,20 @@ description: Learn how cross-project search (CPS) enables you to search across m
 
 # {{cps-cap}} [cross-project-search]
 
-**{{cps-cap}}** ({{cps-init}}) enables you to run a single search request across multiple {{serverless-short}} projects.
-When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all that data from a single place, without having to search each project individually.
+::::{include} /deploy-manage/_snippets/cps-definition.md
+::::
 
 {{cps-cap}} relies on linking projects within your {{ecloud}} organization. After you link projects together, searches from the origin project automatically run across all linked projects.
 
 This overview explains how {{cps}} works, including project linking and security.
-For prerequisites, compatibility requirements, architecture planning, and scope defaults, refer to [Configure {{cps}}](/deploy-manage/cross-project-search-config.md) in **Deploy and manage**.
+For prerequisites, compatibility requirements, architecture planning, and scope defaults, refer to [](/deploy-manage/cross-project-search-config.md).
+
 For details on how search, tags, and project routing work in {{cps-init}}, refer to the following pages:
 
 * [Search in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-search.md): Learn how search expressions, search options, and index resolution work.
 * [Tags in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-tags.md): Learn about predefined and custom project tags and how to use them in queries.
 * [Project routing in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-project-routing.md): Learn how to route searches to specific projects based on tag values.
-* [Manage {{cps}} scope in your project apps](/explore-analyze/cross-project-search/cross-project-search-manage-scope.md): Control which projects are searched as you work in Discover, Dashboards, and other {{kib}} apps.
+* [Manage {{cps-init}} scope in your project apps](/explore-analyze/cross-project-search/cross-project-search-manage-scope.md): Control which projects are searched as you work in Discover, Dashboards, and other {{kib}} apps.
 
 ## {{cps-cap}} as the default behavior for linked projects
 
@@ -65,7 +66,7 @@ You can use `_origin` in search expressions to explicitly target the origin proj
 ## Excluding indices and projects
 
 You can exclude specific indices or projects from a {{cps}} by prefixing a pattern with a dash (`-`).
-This enables you start with a broad search scope and narrow it down by removing specific indices or projects from the results.
+This enables you to start with a broad search scope and narrow it down by removing specific indices or projects from the results.
 
 ### How exclusion works
 
@@ -105,22 +106,16 @@ The following examples assume an origin project with two linked projects: `linke
 
 This section gives you a high-level overview of how security works in {{cps}}.
 
-In {{cps-init}}, access to a project's data is determined by the [roles](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) assigned to you in that project. Your access does not change based on how you perform a search: whether you query directly within a project or access it through {{cps}}, the same permissions apply.
-
-::::{note}
-{{cps-cap}} is not available when performing programmatic searches using {{es}} API keys, since they're project-scoped and they return results from the local project only.
-::::
-
-Access control operates in two stages:
-
-* Authentication verifies the identity associated with a request (for example, a Cloud user or API key) and retrieves that identity's role assignments in each project.
-* Authorization evaluates those roles to determine which actions and resources the request can access within each project.
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-security.md
+:::
 
-For example, if you have a viewer role in project 1, an admin role in project 2, and a custom role in project 3, you can access all three projects through {{cps}}. Each project enforces the permissions associated with the role you have in that project.
+### How access is evaluated
 
-When a {{cps}} query targets a linked project that you have access to, authorization checks are performed locally in that project to determine whether you have the required privileges to access the requested resources.
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md
+:::
 
 **Example**
+
 You have read access to the `logs` index in project 1, but no access to the `logs` index in project 2.
 If you run `GET logs/_search`:
 
@@ -178,7 +173,7 @@ For additional information, refer to the [{{product.painless}} execute API refer
 ::::{include} /deploy-manage/_snippets/cps-limitations-core.md
 ::::
 
-For administrator-focused details including compatibility, architecture patterns, and feature impacts, refer to [Configure {{cps}}](/deploy-manage/cross-project-search-config.md).
+For administrator-focused details including compatibility, architecture patterns, and feature impacts, refer to [](/deploy-manage/cross-project-search-config.md).
 
 ## {{cps-cap}} examples [cps-examples]
 

explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md

@@ -0,0 +1,8 @@
+Access control operates in two stages:
+
+* Authentication verifies the identity associated with a request (for example, a Cloud user or API key) and retrieves that identity's role assignments in each project.
+* Authorization evaluates those roles to determine which actions and resources the request can access within each project.
+
+For example, if you have a viewer role in project 1, an admin role in project 2, and a custom role in project 3, you can access all three projects through {{cps}}. Each project enforces the permissions associated with the role you have in that project.
+
+When a {{cps}} query targets a linked project that you have access to, authorization checks are performed locally in that project to determine whether you have the required privileges to access the requested resources.