Feature Controls - Role Management API Docs #34854
+309
−42
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -32,9 +32,39 @@ that begin with `_` are reserved for system usage. | |
| `elasticsearch`:: (object) Optional {es} cluster and index privileges, valid keys are | ||
| `cluster`, `indices` and `run_as`. For more information, see {xpack-ref}/defining-roles.html[Defining Roles]. | ||
|
|
||
| `kibana`:: (array) An array of objects which specify the <<kibana-privileges>> for this role: | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| [{ | ||
|
There was a problem hiding this comment. Rather than explain all this in prose, I thought it'd be easier to understand if I just had a well-documented JSON snippet instead. There was a problem hiding this comment. This is a good idea. However, some of the lines are hard to read because of horizontal scrolling. I made an attempt to edit them down. There was a problem hiding this comment. My only concern is that we can't link to the "Kibana Privileges" section when using comments within the JSON. Perhaps we could mirror the way that Elasticsearch's role API docs implement the "index privileges": https://www.elastic.co/guide/en/elasticsearch/reference/7.0/security-api-put-role.html |
||
| // An optional base privilege. | ||
| // If specified, must either be ["all"] or ["read"]. | ||
| // Privileges granted here cannot be revoked or downgraded via the `feature` section. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // "all" grants read/write access to all features within Kibana for the specified spaces. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // "read" grants read-only access to all featuers within Kibana for the specified spaces. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "base": [], | ||
|
|
||
| // Object containing privileges for specific features. | ||
| // Privileges specified here will be added to the base privilege, if one was provided. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // For example, specifying `base: ["read"]` will grant read access to every feature, | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // even if they aren't granted anything in this feature section. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // Use the Features API to retrieve a list of available features <1> | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "feature": { | ||
| "advancedSettings": ["all"], | ||
| "discover": ["all"], | ||
| "visualize": ["all"], | ||
| "dashboard": ["read"] | ||
| }, | ||
|
|
||
| // The spaces these privileges should be applied to. | ||
| // To grant access to all spaces, set this to `["*"]`, or omit the value altogether. | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "spaces": ["default", "marketing", "sales"] | ||
| }] | ||
| -------------------------------------------------- | ||
|
|
||
| <1> <<features-api>> | ||
|
There was a problem hiding this comment. note: This relies on the Features API docs created in #34575 |
||
|
|
||
| ===== Example 1 | ||
| Granting read access to all features in all spaces, with full access to Advanced Settings. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
|
|
@@ -54,22 +84,60 @@ PUT /api/security/role/my_kibana_role | |
| "query" : "{\"match\": {\"title\": \"foo\"}}" | ||
| } ] | ||
| }, | ||
| "kibana": [ | ||
| { | ||
| "base": [ | ||
| "read" | ||
| ], | ||
| "feature": { | ||
| "advancedSettings": ["all"] | ||
| }, | ||
| "spaces": [ | ||
| "*" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| -------------------------------------------------- | ||
| // KIBANA | ||
|
|
||
| ===== Example 2 | ||
| Granting "dashboard only" access to only the Marketing space. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| PUT /api/security/role/my_kibana_role | ||
| { | ||
| "metadata" : { | ||
| "version" : 1 | ||
| }, | ||
| "elasticsearch": { | ||
legrego marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "cluster" : [ "all" ], | ||
| "indices" : [ { | ||
| "names" : [ "index1", "index2" ], | ||
| "privileges" : [ "all" ], | ||
| "field_security" : { | ||
| "grant" : [ "title", "body" ] | ||
| }, | ||
| "query" : "{\"match\": {\"title\": \"foo\"}}" | ||
| } ] | ||
| }, | ||
| "kibana": [ | ||
| { | ||
| "base": [], | ||
| "feature": { | ||
| "dashboard": ["read"] | ||
| }, | ||
| "spaces": [ | ||
| "marketing" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| -------------------------------------------------- | ||
|
|
||
| ===== Example 3 | ||
| Granting full access to all features in the Default space. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
|
|
@@ -89,12 +157,19 @@ PUT /api/security/role/my_kibana_role | |
| "query" : "{\"match\": {\"title\": \"foo\"}}" | ||
| } ] | ||
| }, | ||
| "kibana": [ | ||
| { | ||
| "base": ["all"], | ||
| "feature": { | ||
| }, | ||
| "spaces": [ | ||
| "default" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| -------------------------------------------------- | ||
|
|
||
| ==== Response | ||
|
|
||
| A successful call returns a response code of `204` and no response body. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This feature list might be overkill, but I wanted to show an example of a really customized role definition. I can scale it back if that'd be better.