Skip to content
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

[DOCS] Update alias security for data stream aliases #73436

Merged
merged 3 commits into from
May 27, 2021
Merged

[DOCS] Update alias security for data stream aliases #73436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
45cf97f
[DOCS] Update alias security for data stream aliases
jrodewig May 26, 2021
3fa0e16
Address feedback
jrodewig May 27, 2021
942dcfe
Reword
jrodewig May 27, 2021
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
106 changes: 25 additions & 81 deletions x-pack/docs/en/security/authorization/alias-privileges.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<<data-streams,data streams>> and <<alias,aliases>>.
Expand All @@ -9,10 +9,9 @@
==== Data stream privileges

// tag::data-stream-security[]

Use <<privileges-list-indices,indices privileges>> 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 <<privileges-list-indices,index privileges>> to control access to a data
stream. Granting privileges on a data stream grants the same privileges on its
backing indices.
// end::data-stream-security[]

For example, `my-data-stream` consists of two backing indices:
Expand Down Expand Up @@ -64,100 +63,45 @@ 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 <<privileges-list-indices,index privileges>> to control access to an
<<alias,alias>>. Privileges on an index or data stream do not grant privileges
on its aliases. For information about managing aliases, see <<alias>>.

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 <<filter-alias,filtered aliases>> in place of
<<document-level-security,document level security>>. {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 for 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
Copy link
Member

Choose a reason for hiding this comment

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

I assume this section is removed because similar information is available on the alias page? Can we add a link here again to say something like "please see here for how to manage alias"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's correct. I'll add the following sentence to the intro:

For information about managing aliases, see <>.


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
<<document-level-security,document level security>>.
6 changes: 3 additions & 3 deletions x-pack/docs/en/security/authorization/managing-roles.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions x-pack/docs/en/security/limitations.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down