249 lines
5.2 KiB
Text
249 lines
5.2 KiB
Text
[[role-management-api-put]]
|
|
=== Create or update role API
|
|
++++
|
|
<titleabbrev>Create or update role</titleabbrev>
|
|
++++
|
|
|
|
Creates a new {kib} role, or updates the attributes of an existing role. {kib} roles are stored in the
|
|
{es} native realm.
|
|
|
|
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
|
|
|
|
[[role-management-api-put-request]]
|
|
==== Request
|
|
|
|
`PUT /api/security/role/my_kibana_role`
|
|
|
|
[[role-management-api-put-prereqs]]
|
|
==== Prerequisite
|
|
|
|
To use the create or update role API, you must have the `manage_security` cluster privilege.
|
|
|
|
[[role-management-api-response-body]]
|
|
==== Request body
|
|
|
|
`metadata`::
|
|
(Optional, object) In the `metadata` object, keys that begin with `_` are reserved for system usage.
|
|
|
|
`elasticsearch`::
|
|
(Optional, object) {es} cluster and index privileges. Valid keys include `cluster`, `indices`, and `run_as`. For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
|
|
|
|
`kibana`::
|
|
(list) Objects that specify the <<kibana-privileges, Kibana privileges>> for the role:
|
|
|
|
`base` :::
|
|
(Optional, list) A base privilege. When specified, the base must be `["all"]` or `["read"]`.
|
|
When the `base` privilege is specified, you are unable to use the `feature` section.
|
|
"all" grants read/write access to all {kib} features for the specified spaces.
|
|
"read" grants read-only access to all {kib} features for the specified spaces.
|
|
|
|
`feature` :::
|
|
(object) Contains privileges for specific features.
|
|
When the `feature` privileges are specified, you are unable to use the `base` section.
|
|
To retrieve a list of available features, use the <<features-api, features API>>.
|
|
|
|
`spaces` :::
|
|
(list) The spaces to apply the privileges to.
|
|
To grant access to all spaces, set to `["*"]`, or omit the value.
|
|
|
|
[[role-management-api-put-response-codes]]
|
|
==== Response code
|
|
|
|
`204`::
|
|
Indicates a successful call.
|
|
|
|
===== Examples
|
|
|
|
Grant 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
|
|
|
|
Grant 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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
Grant 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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
Grant 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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
Grant access to {kib} 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\"}}"
|
|
} ]
|
|
},
|
|
"kibana": [
|
|
{
|
|
"base": ["all"],
|
|
"feature": {
|
|
},
|
|
"spaces": [
|
|
"default"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// KIBANA
|