Skip to content

Commit

Permalink
Feature Controls - Documentation (#35656) (#36911)
Browse files Browse the repository at this point in the history 
* update spaces images

* add Spaces FC section

* Updates for kibana authorization section

* update plugin development guide

* start adding docs

* remove unused description field from Feature Registry interface

* Update role management API documentation

* Apply suggestions from code review

Thanks, Gail!

Co-Authored-By: legrego <lgregorydev@gmail.com>

* Update docs/api/role-management/put.asciidoc

* update kibana privileges section intro

* relocate link to Role Management API

* update PUT role docs to align with ES

* indicate that base and feature privileges cannot be used at the same time

* restructure kibana privileges section

* add UI and API examples to Kibana Privileges section

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* address PR feedback

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* address pr feedback

* Update docs/api/role-management/put.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/security/index.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

* address PR feedback

* fix merge from master

* Update docs/spaces/managing-spaces.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>
  • Loading branch information
@legrego @gchaps
legrego and gchaps committed May 23, 2019
1 parent 87b9093 commit 6684d5b
Show file tree
Hide file tree
Showing 29 changed files with 770 additions and 133 deletions.
81 changes: 73 additions & 8 deletions docs/api/role-management/get.asciidoc
View file
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": [
"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"
]
}
]
}
--------------------------------------------------
194 changes: 175 additions & 19 deletions docs/api/role-management/put.asciidoc
View file
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"]`.
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,30 +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": {
"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.
===== Example 5
Granting access to both Kibana and Elasticsearch.

[source,js]
--------------------------------------------------
Expand All @@ -87,12 +228,27 @@ PUT /api/security/role/my_kibana_role
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
},
<<<<<<< HEAD
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
=======
"kibana": {
"global": [],
"space": {
"marketing": ["all"],
"engineering": ["read"]
>>>>>>> 83b7ea76b0fd7afcbeff26cd95241ef4b075d12e
}
}
]
}
--------------------------------------------------

==== Response

A successful call returns a response code of `204` and no response body.
3 changes: 3 additions & 0 deletions docs/development/plugin-development.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,16 @@ The Kibana plugin interfaces are in a state of constant development. We cannot

* <<development-plugin-resources>>
* <<development-uiexports>>
* <<development-plugin-feature-registration>>
* <<development-plugin-functional-tests>>
* <<development-plugin-localization>>

include::plugin/development-plugin-resources.asciidoc[]

include::plugin/development-uiexports.asciidoc[]

include::plugin/development-plugin-feature-registration.asciidoc[]

include::plugin/development-plugin-functional-tests.asciidoc[]

include::plugin/development-plugin-localization.asciidoc[]
Expand Down

0 comments on commit 6684d5b

Please sign in to comment.