[DOCS] Adds documentation for secondary authorization headers (#55365)

Co-authored-by: Tim Vernum <tim@adjective.org>

docs/reference/ml/anomaly-detection/apis/preview-datafeed.asciidoc

@@ -32,16 +32,12 @@ structure of the data that will be passed to the anomaly detection engine.
 IMPORTANT: When {es} {security-features} are enabled, the {dfeed} query is
 previewed using the credentials of the user calling the preview {dfeed} API.
 When the {dfeed} is started it runs the query using the roles of the last user
-to create or update it.  If the two sets of roles differ then the preview may
+to create or update it. If the two sets of roles differ then the preview may
 not accurately reflect what the {dfeed} will return when started. To avoid
-such problems, the same user that creates/updates the {dfeed} should preview
-it to ensure it is returning the expected data.
-+
---
-NOTE: It is possible that secondary authorization headers are supplied in the
-request. If this is the case, the secondary authorization headers are used
-instead of the primary headers.
---
+such problems, the same user that creates or updates the {dfeed} should preview
+it to ensure it is returning the expected data. Alternatively, use
+<<http-clients-secondary-authorization,secondary authorization headers>> to
+supply the credentials.
 
 [[ml-preview-datafeed-path-parms]]
 ==== {api-path-parms-title}

docs/reference/ml/anomaly-detection/apis/put-datafeed.asciidoc

@@ -41,10 +41,9 @@ each interval. See {ml-docs}/ml-delayed-data-detection.html[Handling delayed dat
 `.ml-config` index.
 * When {es} {security-features} are enabled, your {dfeed} remembers which roles
 the user who created it had at the time of creation and runs the query using
-those same roles.
-* It is possible that secondary authorization headers are supplied in the
-  request. If this is the case, the secondary authorization headers are used
-  instead of the primary headers.
+those same roles. If you provide
+<<http-clients-secondary-authorization,secondary authorization headers>>, those
+credentials are used instead.
 ====
 
 [[ml-put-datafeed-path-parms]]

docs/reference/ml/anomaly-detection/apis/start-datafeed.asciidoc

@@ -68,7 +68,9 @@ of the latest processed record.
 
 IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
 which roles the last user to create or update it had at the time of
-creation/update and runs the query using those same roles.
+creation/update and runs the query using those same roles. If you provided
+<<http-clients-secondary-authorization,secondary authorization headers>> when
+you created or updated the {dfeed}, those credentials are used instead.
 
 [[ml-start-datafeed-path-parms]]
 ==== {api-path-parms-title}

docs/reference/ml/anomaly-detection/apis/update-datafeed.asciidoc

@@ -33,14 +33,10 @@ change to be applied.
 
 IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
 which roles the user who updated it had at the time of update and runs the query
-using those same roles.
+using those same roles. If you provide
+<<http-clients-secondary-authorization,secondary authorization headers>>, those
+credentials are used instead.
 
-+
---
-NOTE: It is possible that secondary authorization headers are supplied in the
-request. If this is the case, the secondary authorization headers are used
-instead of the primary headers.
---
 [[ml-update-datafeed-path-parms]]
 ==== {api-path-parms-title}
 

docs/reference/ml/df-analytics/apis/put-dfanalytics.asciidoc

@@ -33,9 +33,11 @@ built-in roles and privileges:
 
 For more information, see <<security-privileges>> and <<built-in-roles>>.
 
-NOTE: It is possible that secondary authorization headers are supplied in the
-request. If this is the case, the secondary authorization headers are used
-instead of the primary headers.
+NOTE: The {dfanalytics-job} remembers which roles the user who created it had at
+the time of creation. When you start the job, it performs the analysis using
+those same roles. If you provide
+<<http-clients-secondary-authorization,secondary authorization headers>>, 
+those credentials are used instead.
 
 [[ml-put-dfanalytics-desc]]
 ==== {api-description-title}

docs/reference/ml/df-analytics/apis/start-dfanalytics.asciidoc

@@ -50,6 +50,11 @@ fails to start.
 If the destination index exists, it is used as is. You can therefore set up the
 destination index in advance with custom settings and mappings.
 
+IMPORTANT: When {es} {security-features} are enabled, the {dfanalytics-job}
+remembers which user created it and runs the job using those credentials. If you 
+provided <<http-clients-secondary-authorization,secondary authorization headers>>
+when you created the job, those credentials are used.
+
 [[ml-start-dfanalytics-path-params]]
 ==== {api-path-parms-title}
 

x-pack/docs/en/security/ccs-clients-integrations/http.asciidoc

@@ -12,7 +12,11 @@ Authorization: Basic <TOKEN> <1>
 --------------------------------------------------
 <1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
 
-[float]
+Alternatively, you can use
+<<token-authentication-services,token-based authentication services>>.
+
+[discrete]
+[[http-clients-examples]]
 ==== Client examples
 
 This example uses `curl` without basic auth to create an index:
@@ -46,7 +50,34 @@ curl --user rdeniro:taxidriver -XPUT 'localhost:9200/idx'
 }
 ---------------------------------------------------------
 
-[float]
+[discrete]
+[[http-clients-secondary-authorization]]
+==== Secondary authorization
+
+Some APIs support secondary authorization headers for situations where you want
+tasks to run with a different set of credentials. For example, you can send the
+following header in addition to the basic authentication header:
+
+[source,shell]
+--------------------------------------------------
+es-secondary-authorization: Basic <TOKEN> <1>
+--------------------------------------------------
+<1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
+
+The `es-secondary-authorization` header has the same syntax as the
+`Authorization` header. It therefore also supports the use of
+<<token-authentication-services,token-based authentication services>>. For
+example:
+
+[source,shell]
+--------------------------------------------------
+es-secondary-authorization: ApiKey <TOKEN> <1>
+--------------------------------------------------
+<1> The `<TOKEN>` is computed as `base64(API key ID:API key)`
+
+
+[discrete]
+[[http-clients-libraries]]
 ==== Client libraries over HTTP
 
 For more information about using {security-features} with the language