Skip to content

Commit 5ef7aac

Browse files
lcawltvernum
andauthored
[DOCS] Adds documentation for secondary authorization headers (#55365)
Co-authored-by: Tim Vernum <[email protected]>
1 parent f3870e6 commit 5ef7aac

File tree

7 files changed

+57
-26
lines changed

7 files changed

+57
-26
lines changed

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

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,16 +32,12 @@ structure of the data that will be passed to the anomaly detection engine.
3232
IMPORTANT: When {es} {security-features} are enabled, the {dfeed} query is
3333
previewed using the credentials of the user calling the preview {dfeed} API.
3434
When the {dfeed} is started it runs the query using the roles of the last user
35-
to create or update it. If the two sets of roles differ then the preview may
35+
to create or update it. If the two sets of roles differ then the preview may
3636
not accurately reflect what the {dfeed} will return when started. To avoid
37-
such problems, the same user that creates/updates the {dfeed} should preview
38-
it to ensure it is returning the expected data.
39-
+
40-
--
41-
NOTE: It is possible that secondary authorization headers are supplied in the
42-
request. If this is the case, the secondary authorization headers are used
43-
instead of the primary headers.
44-
--
37+
such problems, the same user that creates or updates the {dfeed} should preview
38+
it to ensure it is returning the expected data. Alternatively, use
39+
<<http-clients-secondary-authorization,secondary authorization headers>> to
40+
supply the credentials.
4541

4642
[[ml-preview-datafeed-path-parms]]
4743
==== {api-path-parms-title}

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,9 @@ each interval. See {ml-docs}/ml-delayed-data-detection.html[Handling delayed dat
4141
`.ml-config` index.
4242
* When {es} {security-features} are enabled, your {dfeed} remembers which roles
4343
the user who created it had at the time of creation and runs the query using
44-
those same roles.
45-
* It is possible that secondary authorization headers are supplied in the
46-
request. If this is the case, the secondary authorization headers are used
47-
instead of the primary headers.
44+
those same roles. If you provide
45+
<<http-clients-secondary-authorization,secondary authorization headers>>, those
46+
credentials are used instead.
4847
====
4948

5049
[[ml-put-datafeed-path-parms]]

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,9 @@ of the latest processed record.
6868

6969
IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
7070
which roles the last user to create or update it had at the time of
71-
creation/update and runs the query using those same roles.
71+
creation/update and runs the query using those same roles. If you provided
72+
<<http-clients-secondary-authorization,secondary authorization headers>> when
73+
you created or updated the {dfeed}, those credentials are used instead.
7274

7375
[[ml-start-datafeed-path-parms]]
7476
==== {api-path-parms-title}

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

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,10 @@ change to be applied.
3333

3434
IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
3535
which roles the user who updated it had at the time of update and runs the query
36-
using those same roles.
36+
using those same roles. If you provide
37+
<<http-clients-secondary-authorization,secondary authorization headers>>, those
38+
credentials are used instead.
3739

38-
+
39-
--
40-
NOTE: It is possible that secondary authorization headers are supplied in the
41-
request. If this is the case, the secondary authorization headers are used
42-
instead of the primary headers.
43-
--
4440
[[ml-update-datafeed-path-parms]]
4541
==== {api-path-parms-title}
4642

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,11 @@ built-in roles and privileges:
3333

3434
For more information, see <<security-privileges>> and <<built-in-roles>>.
3535

36-
NOTE: It is possible that secondary authorization headers are supplied in the
37-
request. If this is the case, the secondary authorization headers are used
38-
instead of the primary headers.
36+
NOTE: The {dfanalytics-job} remembers which roles the user who created it had at
37+
the time of creation. When you start the job, it performs the analysis using
38+
those same roles. If you provide
39+
<<http-clients-secondary-authorization,secondary authorization headers>>,
40+
those credentials are used instead.
3941

4042
[[ml-put-dfanalytics-desc]]
4143
==== {api-description-title}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ fails to start.
5050
If the destination index exists, it is used as is. You can therefore set up the
5151
destination index in advance with custom settings and mappings.
5252

53+
IMPORTANT: When {es} {security-features} are enabled, the {dfanalytics-job}
54+
remembers which user created it and runs the job using those credentials. If you
55+
provided <<http-clients-secondary-authorization,secondary authorization headers>>
56+
when you created the job, those credentials are used.
57+
5358
[[ml-start-dfanalytics-path-params]]
5459
==== {api-path-parms-title}
5560

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

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@ Authorization: Basic <TOKEN> <1>
1212
--------------------------------------------------
1313
<1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
1414

15-
[float]
15+
Alternatively, you can use
16+
<<token-authentication-services,token-based authentication services>>.
17+
18+
[discrete]
19+
[[http-clients-examples]]
1620
==== Client examples
1721

1822
This example uses `curl` without basic auth to create an index:
@@ -46,7 +50,34 @@ curl --user rdeniro:taxidriver -XPUT 'localhost:9200/idx'
4650
}
4751
---------------------------------------------------------
4852

49-
[float]
53+
[discrete]
54+
[[http-clients-secondary-authorization]]
55+
==== Secondary authorization
56+
57+
Some APIs support secondary authorization headers for situations where you want
58+
tasks to run with a different set of credentials. For example, you can send the
59+
following header in addition to the basic authentication header:
60+
61+
[source,shell]
62+
--------------------------------------------------
63+
es-secondary-authorization: Basic <TOKEN> <1>
64+
--------------------------------------------------
65+
<1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
66+
67+
The `es-secondary-authorization` header has the same syntax as the
68+
`Authorization` header. It therefore also supports the use of
69+
<<token-authentication-services,token-based authentication services>>. For
70+
example:
71+
72+
[source,shell]
73+
--------------------------------------------------
74+
es-secondary-authorization: ApiKey <TOKEN> <1>
75+
--------------------------------------------------
76+
<1> The `<TOKEN>` is computed as `base64(API key ID:API key)`
77+
78+
79+
[discrete]
80+
[[http-clients-libraries]]
5081
==== Client libraries over HTTP
5182

5283
For more information about using {security-features} with the language

0 commit comments

Comments
 (0)