* 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>
254 lines
5.7 KiB
Text
254 lines
5.7 KiB
Text
[[role-management-api-put]]
|
|
=== Create or Update Role
|
|
|
|
experimental["This API is experimental and may be changed or removed completely in a future release. Although the underlying mechanism of enforcing role-based access control is stable, the APIs for managing the roles are currently experimental."]
|
|
|
|
Creates a new {kib} role or updates the attributes of an existing role. {kib} roles are stored in the
|
|
{es} native realm.
|
|
|
|
NOTE: You cannot access this endpoint via the Console in Kibana.
|
|
|
|
==== Authorization
|
|
|
|
To use this API, you must have at least the `manage_security` cluster privilege.
|
|
|
|
==== Request
|
|
|
|
To create or update a role, issue a PUT request to the
|
|
`/api/security/role/<rolename>` endpoint.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /api/security/role/my_kibana_role
|
|
--------------------------------------------------
|
|
|
|
==== Request Body
|
|
|
|
The following parameters can be specified in the body of a PUT request to add or update a role:
|
|
|
|
`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
|
|
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`:: (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.
|
|
|
|
`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]
|
|
--------------------------------------------------
|
|
PUT /api/security/role/my_kibana_role
|
|
{
|
|
"metadata" : {
|
|
"version" : 1
|
|
},
|
|
"elasticsearch": {
|
|
"cluster" : [ ],
|
|
"indices" : [ ]
|
|
},
|
|
"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
|
|
|
|
===== Example 2
|
|
Granting "dashboard only" access to only the Marketing space.
|
|
|
|
[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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
===== Example 5
|
|
Granting access to both Kibana and Elasticsearch.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /api/security/role/my_kibana_role
|
|
{
|
|
"metadata" : {
|
|
"version" : 1
|
|
},
|
|
"elasticsearch": {
|
|
"cluster" : [ "all" ],
|
|
"indices" : [ {
|
|
"names" : [ "index1", "index2" ],
|
|
"privileges" : [ "all" ],
|
|
"field_security" : {
|
|
"grant" : [ "title", "body" ]
|
|
},
|
|
"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.
|