Skip to content

remote-clusters-privileges-cert.asciidoc - Clarification of user api key privileges #127172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: 8.18
Choose a base branch
from
Open

remote-clusters-privileges-cert.asciidoc - Clarification of user api key privileges #127172

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c49a04c
Update remote-clusters-privileges-cert.asciidoc
rseldner Apr 22, 2025
b4defaa
Merge branch '8.18' into rseldner-patch-5
rseldner Apr 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/reference/security/authentication/remote-clusters-privileges-cert.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ On the remote cluster that contains the leader index, the {ccr} role requires
the `read_ccr` cluster privilege, and `monitor` and `read` privileges on the
leader index.

NOTE: If requests are authenticated with an <<security-api-create-api-key, API key>>, the API key
requires the above privileges on the **local** cluster, instead of the remote.
NOTE: When using a user <<security-api-create-api-key, API key>>, the required privileges must be granted on the **local cluster** only. The remote cluster will authorize based on the privileges embedded in the API key; **it does not use roles**. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible via cross-cluster operations. See <<remote-clusters-migration>>
Comment on lines +36 to +37
Copy link
Contributor

@shainaraskas shainaraskas Apr 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did a small copyedit

one thing that remains unclear to me is the role of the API key in this flow, given that it is discussing TLS cert authentication. perhaps we have a better link we can provide to explain how the API key is related?

Suggested change
NOTE: When using a user <<security-api-create-api-key, API key>>, the required privileges must be granted on the **local cluster** only. The remote cluster will authorize based on the privileges embedded in the API key; **it does not use roles**. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible via cross-cluster operations. See <<remote-clusters-migration>>
[NOTE]
====
When using a user <<security-api-create-api-key, API key>>, the required privileges must be granted on the local cluster.
The remote cluster does not use roles, and instead authorizes the request based on the privileges embedded in the API key. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible through cross-cluster operations. To learn how to migrate from TLS certificate authentication to API key authentication, refer to <<remote-clusters-migration>>.
====

Copy link
Contributor

@shainaraskas shainaraskas Apr 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fyi this snippet appears in at least two places:

https://www.elastic.co/guide/en/elasticsearch/reference/8.18/_configure_privileges_for_cross_cluster_replication_2.html

https://www.elastic.co/guide/en/elasticsearch/reference/8.18/remote-clusters-cert.html#remote-clusters-privileges-ccr

as a result, we might want to pare back this note so it still makes sense in the context of the ccr-centric page

Copy link
Contributor Author

@rseldner rseldner May 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one thing that remains unclear to me is the role of the API key in this flow, given that it is discussing TLS cert authentication. perhaps we have a better link we can provide to explain how the API key is related?

We were already making a note about the use of an API key with this trust model. I am building on that same note with more specifics.

The doc is about TLS based trust between remote clusters.
But the way the CCS/CCR requests are authorized are contingent on how those requests were authenticated (i.e. a request from someone using username/password is authorized differently than someone using an apikey)

I believe the same applies to both CCS and CCR.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to leave the word "requests" in then if this is specifically about the user submitting the request after CCR/CCS is set up

Suggested change
NOTE: When using a user <<security-api-create-api-key, API key>>, the required privileges must be granted on the **local cluster** only. The remote cluster will authorize based on the privileges embedded in the API key; **it does not use roles**. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible via cross-cluster operations. See <<remote-clusters-migration>>
[NOTE]
====
When a request to a remote cluster is authenticated using an <<security-api-create-api-key, API key>>, the required privileges must be granted on the local cluster.
The remote cluster does not use roles, and instead authorizes the request based on the privileges embedded in the API key. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible through cross-cluster operations. To learn how to migrate from TLS certificate authentication to API key authentication, refer to <<remote-clusters-migration>>.
====

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.

Let's tweak this slightly:

As a result, an API key's access is independent of roles defined on the remote cluster.

I want to avoid customers thinking of an API key's permission as being at all linked to a user's role on the remote -- they're entirely independent and while it's true that they are "broader or more limited" I think we want a stronger statement about how remote roles and API key permissions are entirely orthogonal.


NOTE: If requests are issued <<run-as-privilege,on behalf of other users>>,
then the authenticating user must have the `run_as` privilege on the remote
Expand Down Expand Up @@ -136,8 +136,8 @@ local and remote clusters, and then create a user with the required roles.
On the remote cluster, the {ccs} role requires the `read` and
`read_cross_cluster` privileges for the target indices.

NOTE: If requests are authenticated with an <<security-api-create-api-key, API key>>, the API key
requires the above privileges on the **local** cluster, instead of the remote.
NOTE: When using a user <<security-api-create-api-key, API key>>, the required privileges must be granted on the **local cluster** only. The remote cluster will authorize based on the privileges embedded in the API key; **it does not use roles**. As a result, an API key may have broader or more limited access than the same user’s current role on the remote cluster.
For stricter and more predictable access control, consider using the <<remote-clusters-api-key, cross-cluster API key trust model>>, which gives remote clusters full control over what data is accessible via cross-cluster operations. See <<remote-clusters-migration>>

NOTE: If requests are issued <<run-as-privilege,on behalf of other users>>,
then the authenticating user must have the `run_as` privilege on the remote
Expand Down Expand Up @@ -299,4 +299,4 @@ POST /_security/role/logstash-reader
}
]
}
----
----