[DOCS] Add docs for Application Privileges #32635
Conversation
tvernum
added
review
v7.0.0
:Security/Authorization
|
Pinging @elastic/es-security |
|
Pinging @elastic/es-docs |
|
The has privileges API page links to https://www.elastic.co/guide/en/elastic-stack-overview/master/security-privileges.html . Should application privileges be referenced there as well? |
| @@ -57,6 +65,13 @@ GET _xpack/security/user/_has_privileges | |||
| "names": [ "inventory" ], | |||
| "privileges" : [ "read", "write" ] | |||
| } | |||
| ], | |||
| "application": [ | |||
There was a problem hiding this comment.
The intro for this example should be changed to say "...checks whether the current user has a specific set of cluster, index, and application privileges"
| specified resources. May be either application privilege names, or the names of | ||
| actions that are granted by those privileges | ||
| `resources`::: (list) A list of resource names against which the privileges | ||
| should be checked |
There was a problem hiding this comment.
This description and example aren't enough to explain application privileges, in my opinion. We should add a link to a page that explains the concept in more detail.
| {xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges]. | ||
|
|
||
| ==== Request | ||
|
|
There was a problem hiding this comment.
Can we separate these into separate pages for the various APIs (similar to the separate pages for creating and deleting ML objects e.g. https://www.elastic.co/guide/en/elasticsearch/reference/master/ml-apis.html)? If so, I can do that split.
There was a problem hiding this comment.
Yes, that would be great. I followed the example from other security APIs and didn't realise we had a precedent for separate pages.
|
|
||
| ==== Description | ||
|
|
||
| Application privileges allow Elasticsearch to act as an _oracle_ for security |
There was a problem hiding this comment.
Is this use of the term "oracle" well known? It didn't seem obvious when I search on that term.
There was a problem hiding this comment.
No, I don't think it's well enough known, but unfortunateIy couldn't find a better word. Any suggestions?
Probably I just need to restructure this sentence to not need a noun to describe ES's role here.
There was a problem hiding this comment.
may be ... to act as the source of truth for security decisions that ...
There was a problem hiding this comment.
Oh, I hate that source of truth phrase (probably a reaction to working on too many "single view of customer" projects). You'd need to offer a lot of 🍻 to convince me to put it in this doc 😈
|
It seems to me that we should describe the concept of application privileges in a high-level overview page (e.g. add them to https://www.elastic.co/guide/en/elastic-stack-overview/master/authorization.html). |
Yeah, I started by describing the APIs and then expanded from there, and I think it led to the wrong place. |
|
@lcawl Looking at this more closely, I don't think the Overview page makes sense, because it currently only documents very high level concepts (e.g. it doesn't even explain the difference between cluster and index privileges). My propsal would be to add something to privileges.asciidoc ( I'll start by writing something as a new section in privileges.asciidoc, and if it seems to be the wrong level of detail for that page we can move it to be a standalone doc and link it in. |
|
Re: #32635 (comment), I've created elastic/stack-docs#104 to add that information in the Stack Overview. |
lcawl
force-pushed
the
docs/app-privs
branch
2 times, most recently
from
df236b3
to
bb285a0
Compare
|
|
||
| ==== Examples | ||
|
|
||
| The following example deletes the `write` application privilege from the |
There was a problem hiding this comment.
nit: write -> read
There was a problem hiding this comment.
LGTM Tim. I see it's rather scant, but since these APIs and data structures are for inner use - inside the stack - it's better this way; No need to get too abstract here, as this is docs for programmers 🤓
If I were to add smth I would emphasize the has_privilege API as this is really the crux of it; without it we only define entities and APIs to manage them. Specifically, there might be some examples.
One last thing I would like to know, from a programmer point of view, is if there are any referential integrity checks between the privilege name in the role descriptor and the defined privileges. Do I need to define all privileges before a role descriptor can use them? What happens If I delete a privilege that is referred to in a role? Just drop a line on the topic, and it will suit me :)
| To check a user's application privileges, use the | ||
| <<security-api-has-privileges,has privileges API>>. | ||
|
|
||
| //// |
There was a problem hiding this comment.
Let's just delete this commented out part now that the support for this has been removed
| included as path parameters, the body of the request is a JSON object that | ||
| includes the following fields: | ||
|
|
||
| `application`:: (string) The name of the application to which this privilege |
There was a problem hiding this comment.
technically this is accepted but is optional. I suggest we remove it.
| belongs. This field is optional, but if it exists it must match the application | ||
| name in the path parameter. | ||
|
|
||
| `name`:: (string) The name of the privilege to store. This field is optional, |
There was a problem hiding this comment.
technically this is still accepted but is optional. I suggest we remove it.
| { | ||
| "myapp": { | ||
| "read": { | ||
| "application": "myapp", |
There was a problem hiding this comment.
if we do remove the field from above, I suggest we also remove this line
| "myapp": { | ||
| "read": { | ||
| "application": "myapp", | ||
| "name": "read", |
There was a problem hiding this comment.
if we do remove the field from above, I suggest we also remove this line
| PUT /_xpack/security/privilege | ||
| { | ||
| "myapp": { | ||
| "read": { |
There was a problem hiding this comment.
nit: seems like this could be formatted better in regards to indentation
|
I rebased and ran gradle successfully locally, so I think they're good to go. |
|
NOTE: I also updated the page titles of all security APIs that both create and update something (e.g. from "create user API" to "create or update user API"). This type of title matches what they do in Kibana and I think it's clearer: https://www.elastic.co/guide/en/kibana/current/role-management-api-put.html |
* es/master: (62 commits) [DOCS] Add docs for Application Privileges (#32635) Add versions 5.6.12 and 6.4.1 Do NOT allow termvectors on nested fields (#32728) [Rollup] Return empty response when aggs are missing (#32796) [TEST] Add some ACL yaml tests for Rollup (#33035) Move non duplicated actions back into xpack core (#32952) Test fix - GraphExploreResponseTests should not randomise array elements Closes #33086 Use `addIfAbsent` instead of checking if an element is contained TESTS: Fix Random Fail in MockTcpTransportTests (#33061) HLRC: Fix Compile Error From Missing Throws (#33083) [DOCS] Remove reload password from docs cf. #32889 HLRC: Add ML Get Buckets API (#33056) Watcher: Improve error messages for CronEvalTool (#32800) Search: Support of wildcard on docvalue_fields (#32980) Change query field expansion (#33020) INGEST: Cleanup Redundant Put Method (#33034) SQL: skip uppercasing/lowercasing function tests for AZ locales as well (#32910) Fix the default pom file name (#33063) Switch ml basic tests to new style Requests (#32483) Switch some watcher tests to new style Requests (#33044) ...
* es/6.x: (58 commits) [DOCS] Add docs for Application Privileges (#32635) Add versions 5.6.12 and 6.4.1 [Rollup] Return empty response when aggs are missing (#32796) [TEST] Add some ACL yaml tests for Rollup (#33035) Test fix - GraphExploreResponseTests should not randomise array elements Closes #33086 Use `addIfAbsent` instead of checking if an element is contained HLRC: Fix Compile Error From Missing Throws (#33083) [DOCS] Remove reload password from docs cf. #32889 Use a dedicated ConnectionManger for RemoteClusterConnection (#32988) Watcher: Improve error messages for CronEvalTool (#32800) HLRC: Add ML Get Buckets API (#33056) Change query field expansion (#33020) Search: Support of wildcard on docvalue_fields (#32980) Add beta label to MSI on install Elasticsearch page (#28126) SQL: skip uppercasing/lowercasing function tests for AZ locales as well (#32910) [DOCS] Drafts Elasticsearch 6.4.0 release notes (#33039) Fix the default pom file name (#33063) Fix backport of switch ml basic tests to new style Requests (#32483) Switch ml basic tests to new style Requests (#32483) Switch some watcher tests to new style Requests (#33044) ...
* ccr: (71 commits) Make CCR QA tests build again (elastic#33113) Add hook to skip asserting x-content equivalence (elastic#33114) Muted testListenersThrowingExceptionsDoNotCauseOtherListenersToBeSkipped [Rollup] Move getMetadata() methods out of rollup config objects (elastic#32579) fixed not returning response instance Muted testEmptyAuthorizedIndicesSearchForAllDisallowNoIndices Update Google Cloud Storage Library for Java (elastic#32940) Remove unsupported Version.V_5_* (elastic#32937) Required changes after merging in master branch. [DOCS] Add docs for Application Privileges (elastic#32635) Add versions 5.6.12 and 6.4.1 Do NOT allow termvectors on nested fields (elastic#32728) [Rollup] Return empty response when aggs are missing (elastic#32796) [TEST] Add some ACL yaml tests for Rollup (elastic#33035) Move non duplicated actions back into xpack core (elastic#32952) Test fix - GraphExploreResponseTests should not randomise array elements Closes elastic#33086 Use `addIfAbsent` instead of checking if an element is contained TESTS: Fix Random Fail in MockTcpTransportTests (elastic#33061) HLRC: Fix Compile Error From Missing Throws (elastic#33083) [DOCS] Remove reload password from docs cf. elastic#32889 ...
privilege checking
"application" privileges, and "global" privileges