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.
 
@@ -62,7 +63,7 @@ To be available for linking, projects must meet the following requirements:
 - You can link any combination of {{product.elasticsearch}}, {{product.observability}}, and {{product.security}} projects in the same organization.
 - {{sec-serverless}} and {{obs-serverless}} projects require the **Complete** feature tier. Projects on the **Essentials** tier are not compatible with {{cps}}.
 
-Only compatible projects appear in the [{{cps}} linking wizard](/deploy-manage/cross-project-search-config/cps-config-link-and-manage.md#cps-link-projects). If a project you expected to link to is missing from the list, it might not meet the requirements, or you might not have the necessary [permissions](#cps-prerequisites) on the project.
+Only compatible projects appear in the [{{cps}} linking wizard](/deploy-manage/cross-project-search-config/cps-config-link-and-manage.md#cps-link-projects). If a project you expected to link to is missing from the list, it might not meet the requirements, or you might not have the necessary [permissions](#cps-compatibility) on the project.
 
 % TODO cf https://github.com/elastic/docs-content/pull/5190
 
@@ -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

@@ -9,34 +9,26 @@ navigation_title: "Access and scope"
 
 # Manage access and scope for {{cps}} [cps-access-and-scope]
 
-This page explains how user permissions and scope affect {{cps}} ({{cps-init}}) behavior. 
+This page explains how user permissions and scope affect [{{cps}}](/deploy-manage/cross-project-search-config.md) ({{cps-init}}) behavior, and how to set a default scope at the space level.
 
-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).
+For details about how {{cps-init}} scope works in {{kib}}, refer to [](/explore-analyze/cross-project-search/cross-project-search-manage-scope.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 
 
@@ -59,14 +51,14 @@ Users can also set the scope at the query level, using [qualified search express
 By default, an unqualified search from an origin project targets the searchable resources in **all** linked projects, plus the searchable resources in the origin project. This default scope is intentionally broad, to provide the best user experience for searching across linked projects. 
 
 :::{important}
-The system default {{cps-init}} scope can cause unexpected behavior, especially for alerts and dashboards that operate on the new combined dataset of the origin and all linked projects. To limit this behavior, set the [default {{cps-init}} scope for each space](#cps-default-search-scope), _before_ you link projects.
+The system-level default {{cps-init}} scope can cause unexpected behavior, especially for alerts and dashboards that operate on the new combined dataset of the origin and all linked projects. To limit this behavior, set the [default {{cps-init}} scope for each space](#cps-default-search-scope), _before_ you link projects.
 :::
 
 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)
@@ -76,7 +68,7 @@ The scope controls which projects receive the search request, while [querying an
 
 ### Set the default {{cps-init}} scope for a space [cps-default-search-scope]
 
-You can adjust the {{cps-init}} system default by setting a narrower {{cps}} scope for each space. This setting determines the default search scope for the space. Users can override both the system default and the space-level default by setting their preferred scope when searching, filtering, or running queries. 
+You can adjust the {{cps-init}} system-level default scope by setting a narrower {{cps}} scope for each space. This setting determines the default search scope for the space. Users can override both the system-level default and the space-level default by setting their preferred scope when searching, filtering, or running queries. 
 
 :::{tip}
 For best results, set the default {{cps-init}} scope for each space **before** you link projects.
@@ -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

@@ -11,7 +11,7 @@ navigation_title: "Link and manage projects"
 
 This page explains how to link {{serverless-full}} projects for {{cps}} ({{cps-init}}), manage your linked projects, and unlink projects you no longer need to search across.
 
-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).
+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).
 
 ## Before you begin
 
@@ -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).