[DOCS] Updating doc level security limitations (#64426) (#64660)

* Updating doc level security limitations.

* Incorporating review feedback.

* Changes from review feedback.

* Remove statement about the stats API.
This commit is contained in:
Adam Locke 2020-11-05 11:54:38 -05:00 committed by GitHub
parent 51e9d6f227
commit 358c522f16
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 58 additions and 37 deletions

View File

@ -7,15 +7,27 @@ In particular, it restricts which documents can be accessed from document-based
read APIs. read APIs.
To enable document level security, you use a query to specify the documents that To enable document level security, you use a query to specify the documents that
each role can access. The document query is associated with a particular data each role can access. The document `query` is associated with a particular data
stream, index, or wildcard (`*`) pattern and operates in conjunction with the stream, index, or wildcard (`*`) pattern and operates in conjunction with the
privileges specified for the data streams and indices. privileges specified for the data streams and indices.
The specified document `query`:
* Expects the same format as if it was defined in the search request
* Supports <<templating-role-query,templating a role query>> that can access
the details of the currently authenticated user
* Accepts queries written as either string values or nested JSON
* Supports the majority of the {es}
<<query-dsl,Query Domain Specific Language (DSL)>>, with <<field-document-limitations,some limitations>> for field and document level security
IMPORTANT: Omitting the `query` parameter entirely disables document level
security for the respective indices permission entry.
The following role definition grants read access only to documents that The following role definition grants read access only to documents that
belong to the `click` category within all the `events-*` data streams and indices: belong to the `click` category within all the `events-*` data streams and indices:
[source,console] [source,console]
-------------------------------------------------- ----
POST /_security/role/click_role POST /_security/role/click_role
{ {
"indices": [ "indices": [
@ -26,19 +38,33 @@ POST /_security/role/click_role
} }
] ]
} }
-------------------------------------------------- ----
NOTE: Omitting the `query` entry entirely disables document level security for You can write this same query using nested JSON syntax:
the respective indices permission entry.
The specified `query` expects the same format as if it was defined in the [source,console]
search request and supports the full {es} {ref}/query-dsl.html[Query DSL]. ----
POST _security/role/click_role
{
"indices": [
{
"names": [ "events-*" ],
"privileges": [ "read" ],
"query": {
"match": {
"category": "click"
}
}
}
]
}
----
For example, the following role grants read access only to the documents whose The following role grants read access only to the documents whose
`department_id` equals `12`: `department_id` equals `12`:
[source,console] [source,console]
-------------------------------------------------- ----
POST /_security/role/dept_role POST /_security/role/dept_role
{ {
"indices" : [ "indices" : [
@ -51,8 +77,4 @@ POST /_security/role/dept_role
} }
] ]
} }
-------------------------------------------------- ----
NOTE: `query` also accepts queries written as string values.
For more information, see <<field-and-document-access-control>>.

View File

@ -9,8 +9,8 @@
[discrete] [discrete]
=== Plugins === Plugins
Elasticsearch's plugin infrastructure is extremely flexible in terms of what can {es}'s plugin infrastructure is extremely flexible in terms of what can
be extended. While it opens up Elasticsearch to a wide variety of (often custom) be extended. While it opens up {es} to a wide variety of (often custom)
additional functionality, when it comes to security, this high extensibility level additional functionality, when it comes to security, this high extensibility level
comes at a cost. We have no control over the third-party plugins' code (open comes at a cost. We have no control over the third-party plugins' code (open
source or not) and therefore we cannot guarantee their compliance with source or not) and therefore we cannot guarantee their compliance with
@ -20,7 +20,7 @@ officially supported on clusters with {security-features} enabled.
[discrete] [discrete]
=== Changes in wildcard behavior === Changes in wildcard behavior
Elasticsearch clusters with the {security-features} enabled apply the `/_all` {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 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. privileges for, not all data streams, indices, and index aliases on the cluster.
@ -42,40 +42,39 @@ documents through the
<<field-and-document-access-control, document-level security>> feature. <<field-and-document-access-control, document-level security>> feature.
[discrete] [discrete]
[[field-document-limitations]]
=== Field and document level security limitations === Field and document level security limitations
When a user's role enables document or field level security for a data stream or index: When a user's role enables document or <<field-level-security,field level security>> for a data stream or index:
* The user cannot perform write operations: * The user cannot perform write operations:
** The update API isn't supported. ** The update API isn't supported.
** Update requests included in bulk requests aren't supported. ** Update requests included in bulk requests aren't supported.
* The request cache is disabled for search requests. * The request cache is disabled for search requests.
When a user's role enables document level security for a data stream or index: When a user's role enables <<document-level-security,document level security>> for a data stream or index:
* Document level security isn't applied for APIs that aren't document based.
An example is the field stats API.
* Document level security doesn't affect global index statistics that relevancy * Document level security doesn't affect global index statistics that relevancy
scoring uses. So this means that scores are computed without taking the role scoring uses. This means that scores are computed without taking the role
query into account. Note that documents not matching with the role query are query into account. Documents that don't match the role query are
never returned. never returned.
* The `has_child` and `has_parent` queries aren't supported as query in the * The `has_child` and `has_parent` queries aren't supported as query parameters
role definition. The `has_child` and `has_parent` queries can be used in the in the role definition. The `has_child` and `has_parent` queries can be used in
search API with document level security enabled. the search API with document level security enabled.
* Any query that makes remote calls to fetch data to query by isn't supported. * <<date-math,Date math>> expressions cannot contain `now` in <<ranges-on-dates,range queries with date fields>>
The following queries aren't supported: * Any query that makes remote calls to fetch query data isn't supported,
** The `terms` query with terms lookup isn't supported. including the following queries:
** The `geo_shape` query with indexed shapes isn't supported. ** `terms` query with terms lookup
** The `percolate` query isn't supported. ** `geo_shape` query with indexed shapes
* If suggesters are specified and document level security is enabled then ** `percolate` query
the specified suggesters are ignored. * If suggesters are specified and document level security is enabled, the specified suggesters are ignored.
* A search request cannot be profiled if document level security is enabled. * A search request cannot be profiled if document level security is enabled.
[discrete] [discrete]
[[alias-limitations]] [[alias-limitations]]
=== Index and field names can be leaked when using aliases === Index and field names can be leaked when using aliases
Calling certain Elasticsearch APIs on an alias can potentially leak information Calling certain {es} APIs on an alias can potentially leak information
about indices that the user isn't authorized to access. For example, when you get about indices that the user isn't authorized to access. For example, when you get
the mappings for an alias with the `_mapping` API, the response includes the the mappings for an alias with the `_mapping` API, the response includes the
index name and mappings for each index that the alias applies to. index name and mappings for each index that the alias applies to.