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
Closed

Feature Controls - Role Management API Docs #34854

Show file tree
Hide file tree
Changes from 7 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"
]
}
]
}
--------------------------------------------------
111 changes: 93 additions & 18 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,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`:: (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`:: (array) An array of objects that specifies the <<kibana-privileges>> for this role:
[source,js]
--------------------------------------------------
[{
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"].
// You can't revoke or downgrade privileges via the `feature` section.
// "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.
"base": [],

// Object containing privileges for specific features.
// Privileges are added to the base privilege, if one is provided.
// For example, specifying `base: ["read"]` grants users read access to every feature,
// 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>
"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.
"spaces": ["default", "marketing", "sales"]
}]
--------------------------------------------------

<1> <<features-api>>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: This relies on the Features API docs created in #34575


===== Example
===== Example 1
Granting read access to all features in all spaces, with full access to Advanced Settings.

[source,js]
--------------------------------------------------
Expand All @@ -54,22 +84,60 @@ PUT /api/security/role/my_kibana_role
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
},
"kibana": {
"global": ["all"]
}
"kibana": [
{
"base": [
"read"
],
"feature": {
"advancedSettings": ["all"]
},
"spaces": [
"*"
]
}
]
}
--------------------------------------------------
// KIBANA

==== Response

A successful call returns a response code of `204` and no response body.
===== 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"
]
}
]
}
--------------------------------------------------

==== 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 3
Granting full access to all features in the Default space.

[source,js]
--------------------------------------------------
Expand All @@ -89,12 +157,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.
26 changes: 21 additions & 5 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,30 @@
[[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.
Privileges have levels that you can use to manage which features users can access. Roles have privileges to determine whether users have write or read access.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of trying to discuss the concept of "levels", would it simplify this to just have two sections: "Base privileges" and "Feature privileges"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like this?
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's perfect, since we won't be referencing this from the "Role Management UI docs", do you mind integrating this within the role api docs themselves?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll make those changes, but I'd prefer to wait on integrating until we have the rest of the doc updates in place: we have almost 10 references to this section today, so I want to see what those sections look like after we've updated them for Feature Controls.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kobelb Last we talked, we had discussed including more context here to help users understand where this is used. What are your thoughts on something like this?

image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it!


For more information and examples, consult the <<role-management-api-put, Role Management API>>.

==== Privilege levels

You can assign privileges the following levels:

[horizontal]
`base`::
legrego marked this conversation as resolved.
Show resolved Hide resolved
Grants access to all available features in Kibana (Discover, Visualize, Dashboard, and so on).

`feature`::
Grants access to a specific feature.


==== Role privileges

You can assign a role these privileges:

[horizontal]
legrego marked this conversation as resolved.
Show resolved Hide resolved
[[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.
Grants full read-write access.

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