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

[rseldner]

Clarified the NOTEs about user API key behavior in TLS based trust and recommended API key trust model for stricter access control

Will create a corresponding PR for current (need to validate the syntax for other doc references)
https://github.com/elastic/docs-content/blob/main/deploy-manage/remote-clusters/remote-clusters-cert.md

[github-actions]

Documentation preview:

• ✨ Changed pages

[elasticsearchmachine]

@rseldner please enable the option "Allow edits and access to secrets by maintainers" on your PR. For more information, see the documentation.

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[shainaraskas]

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>>.
	====

[shainaraskas]

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

[rseldner]

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.

[shainaraskas]

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>>.
	====