Rehome CCS/CCR permissions#6934
Conversation
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
✅ Elastic Docs Style Checker (Vale)No issues found on modified lines! 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. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: One typo and one Vale wordiness suggestion in the new CCS section (see inline comments). Other Vale findings in changed files (
may,disabled,Disable,and/or, menu arrows) are all in pre-existing, untouched lines. - Jargon: No new jargon issues.
CCS,CCR,API key, andTLSare all adequately contextualised in the new content. - Frontmatter and applies_to: The CCR file's
applies_tochange from the verbosedeployment: eck/ess/ece/selftostack: allis valid and consistent with repo usage. Inline{applies_to}directives on the deprecated TLS cert sections are correctly applied. - Content type fit: The restructuring works. The CCS page was already a reference/how-to hybrid; adding the privilege section fits its existing shape and reader needs.
- Parent issue satisfaction: Based on the PR description, the stated goals (move privilege config out of setup pages into feature pages, slim down setup pages, update links) appear satisfied. The detection rules link update introduces a content accuracy issue worth fixing before merge (see inline comment on line 30).
Nits
cross-cluster-search.mdline 133: Therun_asprivilege in the new TLS cert subsection is plain backtick text, while the parallel CCR file links it to the privilege docs (`(reference/redacted) Consider linking for consistency.cross-cluster-search.mdline 110: "Note that you only need to create this user on the local cluster." uses informal prose while line 176–178 uses a formal::::{note}admonition for the same information in the adjacent TLS section. Minor inconsistency.
Generated by Docs review agent for issue #6934 · 419.8 AIC · ⌖ 25.4 AIC · ⊞ 32.8K
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I've only had time to review the snippet. Sharing a comment about it. As it's a snippet used in a lot of pages I think we should give a bit of extra love to it, and also mention the TLS cert-based authentication possibility.
| % this will need improvement in a future PR, as the text below is only valid for API key based security model | ||
|
|
||
| If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster to further restrict the permissions granted by the API key. For more details, refer to [Configure roles and users](/deploy-manage/remote-clusters/remote-clusters-api-key.md#remote-clusters-privileges-api-key). No newline at end of file | ||
| If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster to further restrict the permissions granted by the API key. For more details, refer to [Configure privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md#configure-privileges-for-ccr-api-key) and [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-api-key). No newline at end of file |
There was a problem hiding this comment.
What if we divide the content in 3 paragraphs?
1st) If you are using the API-key based authentication....
2nd) If you are using TLS certificates-based authentication (with a super short explanation of how a role with the same name must exist in both local and remote clusters).
3rd) For more details, refer to....
Also please note that on the first paragraph I'd love to find an alternative to to further restrict the permissions granted by the API key. I believe it's not 100% like that. The effective permissions are the intersection between the API key used for connecting the clusters, and the remote privileges of the user. If the user (not superuser) doesn't have remote privileges they wouldn't be able to access the remote cluster data, so that means that the role is not just to restrict further the privileges.... I'd say something like:
If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define user roles with remote indices privileges on the local cluster to specify permissions on remote resources.
(or something equivalent. If you find it useful to say something about the effective permissions, or that the permissions provided by the role cannot exceed the API key permissions that would also be OK!)
I know that original sentence wasn't yours, maybe it was mine :)
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I've suggested some changes, I think it's a good time to refine and enhance some of the content at the same time as doing this movement.
I think the suggested changes are low effort, but feel free to ignore any of them as we could leave them for a later stage.
| * {{ccs-cap}} requires different security privileges on the local cluster and remote cluster. Refer to [Configure privileges](#configure-privileges-for-ccs) for details. | ||
|
|
||
|
|
||
| ## Configure privileges for {{ccs}} [configure-privileges-for-ccs] |
There was a problem hiding this comment.
All the intro in this section could be in a snippet, for your consideration.
|
|
||
| After [remote clusters are connected](/deploy-manage/remote-clusters.md), you can configure which users on your local cluster can search data on remote clusters. The steps depend on the [remote cluster security model](/deploy-manage/remote-clusters/security-models.md) in use: | ||
|
|
||
| * [API key authentication](#configure-privileges-for-ccs-api-key) (recommended), where you create roles with the required privileges on the local cluster. |
There was a problem hiding this comment.
| * [API key authentication](#configure-privileges-for-ccs-api-key) (recommended), where you create roles with the required privileges on the local cluster. | |
| * [API key authentication](#configure-privileges-for-ccs-api-key) (recommended), where you create roles with the required remote privileges on the local cluster. |
|
|
||
| Authorization for {{ccs}} works in two parts: | ||
|
|
||
| * The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. |
There was a problem hiding this comment.
| * The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. | |
| * The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that the remote cluster cluster allows to any user. This key is created and configured during the remote cluster connectivity set up. |
For your consideration, maybe we can remove the last part, or mention that the creation of it it's out of the scope of this document.
| Authorization for {{ccs}} works in two parts: | ||
|
|
||
| * The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. | ||
| * Roles on the local cluster with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) further limit which remote indices each user can search. |
There was a problem hiding this comment.
That sentence is incorrect in the way that it could lead the reader to think that a user without a local role would have ALL privileges that the API key used to interconnect clusters has. And that's not true.
The role on the local cluster can GRANT remote privileges to specific users, and the effective permissions are the interesction of the local roles + the API key used as a boundary.
| Authorization for {{ccs}} works in two parts: | ||
|
|
||
| * The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. | ||
| * Roles on the local cluster with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) further limit which remote indices each user can search. |
There was a problem hiding this comment.
| * Roles on the local cluster with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) further limit which remote indices each user can search. | |
| * Roles on the local cluster with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) grant access to specific remote resources for individual users. A user's effective permissions are the intersection of these role privileges and the permissions allowed by the API key configured for the remote cluster connection. |
We could add that superusers on the local clusters will have all remote privileges by default, allowing them to access the remote cluster resources defined by the API key used during the setup, if we consider that useful.
| ``` | ||
|
|
||
| ::::{note} | ||
| You only need to create this user on the **local** cluster. |
There was a problem hiding this comment.
| You only need to create this user on the **local** cluster. | |
| You only need to create this user and role on the **local** cluster. |
| #### {{kib}} users [configure-privileges-for-ccs-kibana-cert] | ||
|
|
||
| When using {{kib}} to search across multiple clusters, a two-step authorization process determines whether the user can access data streams and indices on a remote cluster: | ||
|
|
||
| * First, the local cluster determines if the user is authorized to access remote clusters. The local cluster is the cluster that {{kib}} is connected to. | ||
| * If the user is authorized, the remote cluster then determines if the user has access to the specified data streams and indices. | ||
|
|
||
| To grant {{kib}} users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify data streams and indices in a remote cluster as `<remote_cluster_name>:<target>`. | ||
|
|
||
| To grant users read access on the remote data streams and indices, you must create a matching role on the remote clusters that grants the `read_cross_cluster` privilege with access to the appropriate data streams and indices. | ||
|
|
||
| For example, you might be actively indexing {{ls}} data on a local cluster and periodically offload older time-based indices to an archive on your remote cluster. You want to search across both clusters, so you must enable {{kib}} users on both clusters. | ||
|
|
||
| On the local cluster, create a `logstash-reader` role that grants `read` and `view_index_metadata` privileges on the local `logstash-*` indices. | ||
|
|
||
| ::::{note} | ||
| If you configure the local cluster as another remote in {{es}}, the `logstash-reader` role on your local cluster also needs to grant the `read_cross_cluster` privilege. | ||
| :::: | ||
|
|
||
| ```console | ||
| POST /_security/role/logstash-reader | ||
| { | ||
| "indices": [ | ||
| { | ||
| "names": [ | ||
| "logstash-*" | ||
| ], | ||
| "privileges": [ | ||
| "read", | ||
| "view_index_metadata" | ||
| ] | ||
| } | ||
| ] | ||
| } |
There was a problem hiding this comment.
Kibana users section feels misleading at first sight! (I know this comes from the old Elasticsearch doc, but it's super old).
It makes the reader to think those users could be different to the users mentioned previously, or that Kibana changes any of this in the way it works, when it doesn't!
We need to clarify the scope in the introduction better, if this is needed at all. The only benefit this section gives is to tell users that they can "REUSE" the role to grant specific privileges on the local cluster (like kibana access + indices read on the local cluster), and in the previous example we used an EMPTY ROLE in the local cluster. And that's pretty obvious and could be covered by a note or something.
^^ That's the only benefit / use case, so I wouldn't create all this "kibana users section" under the deprecated TLS cert-based authentication and instead integrate that possibility in the previous block (actually the user could create an extra role for local resources instead of doing this "hack" but anyway).
-
Also note that the concept that section covers is also applicable to the API key based auth, they could reuse the role to give local privileges.
-
Also note that the order of the role creation is different here: we start with the local role and we end up with the remote cluster role.
Conclussions:
-
I think it's time to simplify this by removing this entire section and just enrich the previous ones.
-
We could include a similar concept to the API-key based authentication: it's a bit obvious but we can remind readers that the user on the local cluster could also have privileges to the local cluster indices and resources with other roles (or the same role) (obvious IMO and the only purpose of this section).
| --- | ||
|
|
||
| # Configure privileges for cross-cluster replication [_configure_privileges_for_ccr_2] | ||
| # Configure privileges for {{ccr}} [_configure_privileges_for_ccr_2] |
There was a problem hiding this comment.
I'd apply the same changes suggested for CCS introduction of permissions, or convert it to a snippet as I think 90% of the text is the same.
Please ensure we clarify that the API key used to interconnect clusters defines the max privileges for any user, and that the local roles grant remote privileges to specific users (they are not just to further restrict the limit of the API key).
By default users do not have any remote privilege (except superusers).
| Certificate based authentication is deprecated. Configure [API key authentication](/deploy-manage/remote-clusters/remote-clusters-api-key.md) instead or follow a guide on how to [migrate remote clusters from certificate to API key authentication](/deploy-manage/remote-clusters/remote-clusters-migrate.md). | ||
| :::: | ||
|
|
||
| After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), create a user role on both the local and remote clusters and assign the necessary privileges. |
There was a problem hiding this comment.
| After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), create a user role on both the local and remote clusters and assign the necessary privileges. | |
| After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), create matching user roles on both the local and remote clusters and assign the necessary privileges. With TLS-based authentication, the local user's role names are forwarded to the remote cluster, which authorizes the request by evaluating roles with the same names defined locally.``` |
There was a problem hiding this comment.
For your evaluation, maybe it's not worthy to give this level of detail.
One thing that would be great is to transmit the message that maintaining and configuring privileges on this security model (tls based auth) is a bit of a mess and much more difficult to maintain than the new security model.
If a local user has 10 roles assigned, the names could potentially match extra roles in the remote cluster, granting privileges that maybe the administrator didn't want.
That's why I consider useful at least mentioning how this work: " the local user's role names are forwarded to the remote cluster, which authorizes the request by evaluating roles with the same names defined locally."
| anchors: | ||
| 'enable-elastic-capabilities': 'elastic-capabilities' | ||
|
|
||
| # Rehome CCS and CCR privileges from remote-clusters-cert.md |
There was a problem hiding this comment.
Impressive work with redirections here!
2 participants
Summary
Fixes #436
This PR moves the cross-cluster privilege configuration out of the remote cluster setup pages and into the feature pages of CCR and CCS where readers actually need it.
Generative AI disclosure
Used Cursor's Auto Agent mode to validate some concepts and find links to update. Also super handy way to create the necessary redirects.