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

Feature Controls - Role Management API Docs #34854

Closed
wants to merge 15 commits into from
+309 −42
Closed

Feature Controls - Role Management API Docs #34854

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
dfd4c99
Update role management API documentation
legrego Apr 10, 2019
32026f3
Apply suggestions from code review
gchaps Apr 16, 2019
e2281d8
Update docs/api/role-management/put.asciidoc
legrego Apr 16, 2019
6234e84
update kibana privileges section intro
legrego Apr 16, 2019
0064bea
Merge branch 'fc/role-api-docs' of github.com:legrego/kibana into fc/…
legrego Apr 16, 2019
15a0437
Merge branch 'master' into fc/role-api-docs
legrego Apr 16, 2019
2feb129
relocate link to Role Management API
legrego Apr 16, 2019
9d85329
Merge branch 'master' into fc/role-api-docs
legrego Apr 17, 2019
92af0ad
update PUT role docs to align with ES
legrego Apr 17, 2019
ec6a85c
indicate that base and feature privileges cannot be used at the same …
legrego Apr 22, 2019
8bbee63
indicate that base and feature privileges cannot be used at the same …
legrego Apr 22, 2019
f99efcc
restructure kibana privileges section
legrego Apr 22, 2019
323608b
Merge branch 'master' of github.com:elastic/kibana into fc/role-api-docs
legrego Apr 24, 2019
4e89fa5
add UI and API examples to Kibana Privileges section
legrego Apr 29, 2019
f43cd7b
Merge branch 'master' of github.com:elastic/kibana into fc/role-api-docs
legrego Apr 29, 2019
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
81 changes: 73 additions & 8 deletions docs/api/role-management/get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,15 @@ representation of the roles.
"cluster": [ ],
"run_as": [ ]
},
"kibana": [ {
"privileges": [ "all" ]
} ],
"kibana": [{
"base": [
"all"
],
"feature": {},
"spaces": [
"*"
]
}]
},
{
"name": "my_admin_role",
Expand Down Expand Up @@ -82,7 +88,7 @@ the `/api/security/role/<rolename>` endpoint:

[source,js]
--------------------------------------------------
GET /api/security/role/my_kibana_role
GET /api/security/role/my_restricted_kibana_role
--------------------------------------------------
// KIBANA

Expand All @@ -94,7 +100,7 @@ representation of the role.
[source,js]
--------------------------------------------------
{
"name": "my_kibana_role",
"name": "my_restricted_kibana_role",
"metadata" : {
"version" : 1
},
Expand All @@ -106,8 +112,67 @@ representation of the role.
"indices": [ ],
"run_as": [ ]
},
"kibana": [ {
"privileges": [ "all" ]
} ],
"kibana": [
{
"base": [
"read"
],
"feature": {},
"spaces": [
"marketing"
]
},
{
"base": [],
"feature": {
"discover": [
Copy link
Member Author

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.

"all"
],
"visualize": [
"all"
],
"dashboard": [
"all"
],
"dev_tools": [
"read"
],
"advancedSettings": [
"read"
],
"indexPatterns": [
"read"
],
"timelion": [
"all"
],
"graph": [
"all"
],
"apm": [
"read"
],
"maps": [
"read"
],
"canvas": [
"read"
],
"infrastructure": [
"all"
],
"logs": [
"all"
],
"uptime": [
"all"
]
},
"spaces": [
"sales",
"default"
]
}
]
}
--------------------------------------------------
196 changes: 171 additions & 25 deletions docs/api/role-management/put.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,21 @@ 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`:: (object) An object that specifies the <<kibana-privileges>>. Valid keys are `global` and `space`. Privileges defined in the `global` key will apply to all spaces within Kibana, and will take precedent over any privileges defined in the `space` key. For example, specifying `global: ["all"]` will grant full access to all spaces within Kibana, even if the role indicates that a specific space should only have `read` privileges.
`kibana`:: (list) A list of objects that specifies the <<kibana-privileges>> for this role:
`base` ::: (list) An optional base privilege. If specified, must either be `["all"]` or `["read"]`.
legrego marked this conversation as resolved.
Show resolved Hide resolved
The `feature` section cannot be used if a base privilege is specified here. You must use one or the other.
"all" grants read/write access to all Kibana features for the specified spaces.
"read" grants read-only access to all Kibana features for the specified spaces.

===== Example
`feature` ::: (object) Object containing privileges for specific features.
The `base` section cannot be used if feature privileges are specified here. You must use one or the other.
Use the <<features-api, Features API>> to retrieve a list of available features.

`spaces` ::: (list) The spaces these privileges should be applied to.
To grant access to all spaces, set this to `["*"]`, or omit the value.

===== Example 1
Granting access to various features in all spaces

[source,js]
--------------------------------------------------
Expand All @@ -44,32 +56,159 @@ PUT /api/security/role/my_kibana_role
"version" : 1
},
"elasticsearch": {
"cluster" : [ "all" ],
"indices" : [ {
"names" : [ "index1", "index2" ],
"privileges" : [ "all" ],
"field_security" : {
"grant" : [ "title", "body" ]
},
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
"cluster" : [ ],
"indices" : [ ]
},
"kibana": {
"global": ["all"]
}
"kibana": [
{
"base": [],
"feature": {
"discover": [
"all"
],
"visualize": [
"all"
],
"dashboard": [
"all"
],
"dev_tools": [
"read"
],
"advancedSettings": [
"read"
],
"indexPatterns": [
"read"
],
"timelion": [
"all"
],
"graph": [
"all"
],
"apm": [
"read"
],
"maps": [
"read"
],
"canvas": [
"read"
],
"infrastructure": [
"all"
],
"logs": [
"all"
],
"uptime": [
"all"
]
},
"spaces": [
"*"
]
}
]
}
--------------------------------------------------
// KIBANA

==== Response
===== Example 2
Granting "dashboard only" access to only the Marketing space.

A successful call returns a response code of `204` and no response body.
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
legrego marked this conversation as resolved.
Show resolved Hide resolved
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"dashboard": ["read"]
},
"spaces": [
"marketing"
]
}
]
}
--------------------------------------------------

===== Example 3
Granting full access to all features in the Default space.

[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
}
]
}
--------------------------------------------------

===== Example 4
Granting different access to different spaces.

[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"dashboard": ["all"]
},
"spaces": [
"default"
]
},
{
"base": ["read"],
"spaces": [
"marketing",
"sales"
]
}
]
}
--------------------------------------------------

==== Granting access to specific spaces
To grant access to individual spaces within {kib}, specify the space identifier within the `kibana` object.

Note: granting access
===== Example 5
Granting access to both Kibana and Elasticsearch.

[source,js]
--------------------------------------------------
Expand All @@ -89,12 +228,19 @@ PUT /api/security/role/my_kibana_role
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
},
"kibana": {
"global": [],
"space": {
"marketing": ["all"],
"engineering": ["read"]
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
}
}
]
}
--------------------------------------------------

==== Response

A successful call returns a response code of `204` and no response body.
21 changes: 12 additions & 9 deletions docs/security/authorization/kibana-privileges.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,17 @@
[[kibana-privileges]]
=== Kibana privileges
legrego marked this conversation as resolved.
Show resolved Hide resolved

This section lists the Kibana privileges that you can assign to a role.
{kib} privileges grant users access to features within {kib}. Roles have privileges to determine whether users have write or read access.

[horizontal]
[[kibana-privileges-all]]
`all`::
All Kibana privileges, can read, write and delete saved searches, dashboards, visualizations,
short URLs, Timelion sheets, graph workspaces, index patterns and advanced settings.
==== Base privileges
Assigning a base privilege grants access to all available features in Kibana (Discover, Visualize, Dashboard, and so on).

`all`:: Grants full read-write access.
`read`:: Grants read-only access.

==== Feature privileges
Assigning a feature privilege grants access to a specific feature.

`all`:: Grants full read-write access.
`read`:: Grants read-only access.

`read`::
Can read saved searches, dashboards, visualizations, short URLs, Timelion sheets, graph workspaces,
index patterns, and advanced settings.