From 45cf97fbd21482e6579d7d16883ac98d058d2959 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 26 May 2021 15:03:15 -0400 Subject: [PATCH 1/3] [DOCS] Update alias security for data stream aliases In 7.14+, you can now create data stream aliases. This updates the related security documentation. It also streamlines the docs to remove redundant examples. --- .../authorization/alias-privileges.asciidoc | 105 ++++-------------- .../authorization/managing-roles.asciidoc | 6 +- x-pack/docs/en/security/limitations.asciidoc | 6 +- 3 files changed, 30 insertions(+), 87 deletions(-) diff --git a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc index 56fd2faf8db5f..c13ac1df7fef8 100644 --- a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc +++ b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[securing-aliases]] -=== Granting privileges for data streams and index aliases +=== Granting privileges for data streams and aliases {es} {security-features} allow you to secure operations executed against <> and <>. @@ -9,10 +9,9 @@ ==== Data stream privileges // tag::data-stream-security[] - -Use <> to control access to -a data stream. Any role or user granted privileges to a data -stream are automatically granted the same privileges to its backing indices. +Use <> to control access to a data +stream. Any role or user granted privileges to a data stream are automatically +granted the same privileges to its backing indices. // end::data-stream-security[] For example, `my-data-stream` consists of two backing indices: @@ -64,100 +63,44 @@ GET .ds-my-data-stream-2099.03.09-000003/_doc/2 // TEST[s/.ds-my-data-stream-2099.03.09-000003/my-index/] [[index-alias-privileges]] -==== Index alias privileges +==== Alias privileges + +Use <> to control access to an +<>. Privileges on an index or data stream do not grant privileges +on its aliases. -An index alias points to one or more indices, -holds metadata and potentially a filter. The {es} {security-features} treat -aliases and indices -the same. Privileges for indices actions are granted on specific indices or -aliases. In order for an indices action to be authorized, the user that executes -it needs to have permissions for that action on all the specific indices or -aliases that the request relates to. +IMPORTANT: Don't use <> in place of +<>. {es} doesn't always apply +alias filters. -Let's look at an example. Assuming we have an index called `2015`, an alias that -points to it called `current_year`, and a user with the following role: +For example, the `current_year` alias points only to the `2015` index. A user is +granted the `read` privilege to the `2015` index. [source,js] --------------------------------------------------- +---- { "names" : [ "2015" ], "privileges" : [ "read" ] } --------------------------------------------------- +---- // NOTCONSOLE -The user attempts to retrieve a document from `current_year`: +When the user attempts to retrieve a document from the `current_year` alias, +{es} rejects the request. [source,console] -------------------------------------------------------------------------------- -GET /current_year/_doc/1 -------------------------------------------------------------------------------- +---- +GET current_year/_doc/1 +---- // TEST[s/^/PUT 2015\n{"aliases": {"current_year": {}}}\nPUT 2015\/_doc\/1\n{}\n/] -The above request gets rejected, although the user has `read` privilege on the -concrete index that the `current_year` alias points to. The correct permission -would be as follows: +To retrieve documents from `current_year`, the user must have the `read` index privilege for the alias. [source,js] --------------------------------------------------- +---- { "names" : [ "current_year" ], "privileges" : [ "read" ] } --------------------------------------------------- -// NOTCONSOLE - -[discrete] -==== Managing aliases - -Unlike creating indices, which requires the `create_index` privilege, adding, -removing and retrieving aliases requires the `manage` permission. Aliases can be -added to an index directly as part of the index creation: - -[source,console] -------------------------------------------------------------------------------- -PUT /2015 -{ - "aliases": { - "current_year": {} - } -} -------------------------------------------------------------------------------- - -or via the dedicated aliases api if the index already exists: - -[source,console] -------------------------------------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "add" : { "index" : "2015", "alias" : "current_year" } } - ] -} -------------------------------------------------------------------------------- -// TEST[s/^/PUT 2015\n/] - -The above requests both require the `manage` privilege on the alias name as well -as the targeted index, as follows: - -[source,js] --------------------------------------------------- -{ - "names" : [ "20*", "current_year" ], - "privileges" : [ "manage" ] -} --------------------------------------------------- +---- // NOTCONSOLE - -The index aliases api also allows also to delete aliases from existing indices. -The privileges required for such a request are the same as above. Both index and -alias need the `manage` permission. - - -[discrete] -==== Filtered aliases - -Aliases can hold a filter, which allows to select a subset of documents that can -be accessed out of all the documents that the physical index contains. These -filters are not always applied and should not be used in place of -<>. diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index 101bf48047477..6c91d1e5a8a0c 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/managing-roles.asciidoc @@ -55,8 +55,8 @@ The following describes the structure of an indices permissions entry: ------- // NOTCONSOLE -<1> A list of data streams, indices, and index aliases to which the permissions - in this entry apply. Wildcard (`*`) expressions are supported. +<1> A list of data streams, indices, and aliases to which the permissions + in this entry apply. Supports wildcards (`*`). <2> The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. <3> Specification for document fields the owners of the role have read access to. @@ -76,7 +76,7 @@ The following describes the structure of an indices permissions entry: [TIP] ============================================================================== The `names` parameter accepts wildcard and regular expressions that may refer to -multiple data streams, indices, and index aliases. +multiple data streams, indices, and aliases. * Wildcard (default) - simple wildcard matching where `*` is a placeholder for zero or more characters, `?` is a placeholder for a single character diff --git a/x-pack/docs/en/security/limitations.asciidoc b/x-pack/docs/en/security/limitations.asciidoc index 13caca5567ce3..4931191424de5 100644 --- a/x-pack/docs/en/security/limitations.asciidoc +++ b/x-pack/docs/en/security/limitations.asciidoc @@ -20,9 +20,9 @@ officially supported on clusters with {security-features} enabled. [discrete] === Changes in wildcard behavior -{es} clusters with the {security-features} enabled apply the `/_all` -wildcard, and all other wildcards, to the data streams, indices, and index aliases that the current user has -privileges for, not all data streams, indices, and index aliases on the cluster. +{es} clusters with the {security-features} enabled apply `_all` and other +wildcards to data streams, indices, and aliases the current user has privileges +for, not all data streams, indices, and aliases on the cluster. [discrete] === Multi document APIs From 3fa0e16716260fd1bdf1fedb3ca46edc18927f77 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Thu, 27 May 2021 08:37:44 -0400 Subject: [PATCH 2/3] Address feedback --- .../authorization/alias-privileges.asciidoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc index c13ac1df7fef8..06e60fffdfbe1 100644 --- a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc +++ b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc @@ -10,15 +10,15 @@ // tag::data-stream-security[] Use <> to control access to a data -stream. Any role or user granted privileges to a data stream are automatically -granted the same privileges to its backing indices. +stream. Granting privileges for a data stream grants the same privileges for its +backing indices. // end::data-stream-security[] For example, `my-data-stream` consists of two backing indices: `.ds-my-data-stream-2099.03.07-000001` and `.ds-my-data-stream-2099.03.08-000002`. -A user is granted the `read` privilege to `my-data-stream`. +A user is granted the `read` privilege for `my-data-stream`. [source,js] -------------------------------------------------- @@ -29,7 +29,7 @@ A user is granted the `read` privilege to `my-data-stream`. -------------------------------------------------- // NOTCONSOLE -Because the user is automatically granted the same privileges to the stream's +Because the user is automatically granted the same privileges for the stream's backing indices, the user can retrieve a document directly from `.ds-my-data-stream-2099.03.08-000002`: @@ -66,15 +66,15 @@ GET .ds-my-data-stream-2099.03.09-000003/_doc/2 ==== Alias privileges Use <> to control access to an -<>. Privileges on an index or data stream do not grant privileges -on its aliases. +<>. Privileges for an index or data stream do not grant privileges +for its aliases. For information about managing aliases, see <>. IMPORTANT: Don't use <> in place of <>. {es} doesn't always apply alias filters. For example, the `current_year` alias points only to the `2015` index. A user is -granted the `read` privilege to the `2015` index. +granted the `read` privilege for the `2015` index. [source,js] ---- @@ -94,7 +94,8 @@ GET current_year/_doc/1 ---- // TEST[s/^/PUT 2015\n{"aliases": {"current_year": {}}}\nPUT 2015\/_doc\/1\n{}\n/] -To retrieve documents from `current_year`, the user must have the `read` index privilege for the alias. +To retrieve documents from `current_year`, the user must have the `read` index +privilege for the alias. [source,js] ---- From 942dcfe3ead296f432983af75132cdfe190d4499 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Thu, 27 May 2021 08:46:06 -0400 Subject: [PATCH 3/3] Reword --- .../security/authorization/alias-privileges.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc index 06e60fffdfbe1..41aadb22f3439 100644 --- a/x-pack/docs/en/security/authorization/alias-privileges.asciidoc +++ b/x-pack/docs/en/security/authorization/alias-privileges.asciidoc @@ -10,7 +10,7 @@ // tag::data-stream-security[] Use <> to control access to a data -stream. Granting privileges for a data stream grants the same privileges for its +stream. Granting privileges on a data stream grants the same privileges on its backing indices. // end::data-stream-security[] @@ -18,7 +18,7 @@ For example, `my-data-stream` consists of two backing indices: `.ds-my-data-stream-2099.03.07-000001` and `.ds-my-data-stream-2099.03.08-000002`. -A user is granted the `read` privilege for `my-data-stream`. +A user is granted the `read` privilege to `my-data-stream`. [source,js] -------------------------------------------------- @@ -29,7 +29,7 @@ A user is granted the `read` privilege for `my-data-stream`. -------------------------------------------------- // NOTCONSOLE -Because the user is automatically granted the same privileges for the stream's +Because the user is automatically granted the same privileges to the stream's backing indices, the user can retrieve a document directly from `.ds-my-data-stream-2099.03.08-000002`: @@ -66,8 +66,8 @@ GET .ds-my-data-stream-2099.03.09-000003/_doc/2 ==== Alias privileges Use <> to control access to an -<>. Privileges for an index or data stream do not grant privileges -for its aliases. For information about managing aliases, see <>. +<>. Privileges on an index or data stream do not grant privileges +on its aliases. For information about managing aliases, see <>. IMPORTANT: Don't use <> in place of <>. {es} doesn't always apply