github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 09:19:04 -04:00
Code Issues Projects Releases Packages Wiki Activity

[8.x] [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) (#197889)

Browse source 
# Backport

This will backport the following commits from `main` to `8.x`:
- [[OpenAPI][DOCS] Add descriptions, examples, responses for role APIs
(#195527)](https://github.com/elastic/kibana/pull/195527)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-10-25T17:13:57Z","message":"[OpenAPI][DOCS]
Add descriptions, examples, responses for role APIs
(#195527)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"02fab7248d5b4e537030252df81bef55d04d0595","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Security","release_note:skip","Feature:Security/Authorization","v9.0.0","docs","v8.16.0","backport:version","v8.17.0"],"number":195527,"url":"https://github.com/elastic/kibana/pull/195527","mergeCommit":{"message":"[OpenAPI][DOCS]
Add descriptions, examples, responses for role APIs
(#195527)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"02fab7248d5b4e537030252df81bef55d04d0595"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/195527","number":195527,"mergeCommit":{"message":"[OpenAPI][DOCS]
Add descriptions, examples, responses for role APIs
(#195527)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"02fab7248d5b4e537030252df81bef55d04d0595"}},{"branch":"8.16","label":"v8.16.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Lisa Cawley 2024-10-28 18:04:48 -07:00 • committed by GitHub
parent 04cc48a389
commit c056931598
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 763 additions and 41176 deletions
Download patch file Download diff file Expand all files Collapse all files

18
docs/api/role-management.asciidoc
View file

@ -1,4 +1,3 @@
[role="xpack"]
[[role-management-api]]
== {kib} role management APIs
@ -6,19 +5,4 @@ Manage the roles that grant <<kibana-privileges, {kib} privileges>>.
WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles.
The following {kib} role management APIs are available:
* <<role-management-api-put, Create or update role API>> to create a new {kib} role, or update the attributes of an existing role
* <<role-management-api-put-bulk, Bulk create or update roles API>> to create a new {kib} roles, or update the attributes of existing roles
* <<role-management-api-get, Get all {kib} roles API>> to retrieve all {kib} roles
* <<role-management-specific-api-get, Get specific role API>> to retrieve a specific role
* <<role-management-api-delete, Delete role API>> to delete a {kib} role
include::role-management/put.asciidoc[]
include::role-management/get.asciidoc[]
include::role-management/get-all.asciidoc[]
include::role-management/delete.asciidoc[]
include::role-management/put-bulk.asciidoc[]
For the latest API details, refer to {api-kibana}/group/endpoint-roles[role APIs].

26
docs/api/role-management/delete.asciidoc
View file

@ -1,26 +0,0 @@
[[role-management-api-delete]]
=== Delete role API
++++
<titleabbrev>Delete role</titleabbrev>
++++
experimental[] Delete a {kib} role.
[[role-management-api-delete-prereqs]]
==== Prerequisite
To use the delete role API, you must have the `manage_security` cluster privilege.
[[role-management-api-delete-request-body]]
==== Request
`DELETE <kibana host>:<port>/api/security/role/my_admin_role`
[[role-management-api-delete-response-codes]]
==== Response codes
`204`::
Indicates a successful call.
`404`::
Indicates an unsuccessful call.

80
docs/api/role-management/get-all.asciidoc
View file

@ -1,80 +0,0 @@
[[role-management-api-get]]
=== Get all {kib} roles API
++++
<titleabbrev>Get all roles</titleabbrev>
++++
experimental[] Retrieve all {kib} roles.
[[role-management-api-get-prereqs]]
==== Prerequisite
To use the get role API, you must have the `manage_security` cluster privilege.
[[role-management-api-retrieve-all-request-body]]
==== Request
`GET <kibana host>:<port>/api/security/role`
[[role-management-api-retrieve-all-response-codes]]
==== Response code
`200`::
Indicates a successful call.
[[role-management-api-retrieve-all-example]]
==== Example
The API returns the following:
[source,sh]
--------------------------------------------------
[
{
"name": "my_kibana_role",
"description": "My kibana role description",
"metadata" : {
"version" : 1
},
"transient_metadata": {
"enabled": true
},
"elasticsearch": {
"indices": [ ],
"cluster": [ ],
"run_as": [ ]
},
"kibana": [{
"base": [
"all"
],
"feature": {},
"spaces": [
"*"
]
}]
},
{
"name": "my_admin_role",
"description": "My admin role description",
"metadata" : {
"version" : 1
},
"transient_metadata": {
"enabled": true
},
"elasticsearch": {
"cluster" : [ "all" ],
"indices" : [ {
"names" : [ "index1", "index2" ],
"privileges" : [ "all" ],
"field_security" : {
"grant" : [ "title", "body" ]
},
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ],
},
"kibana": [ ]
}
]
--------------------------------------------------

106
docs/api/role-management/get.asciidoc
View file

@ -1,106 +0,0 @@
[[role-management-specific-api-get]]
=== Get specific role API
++++
<titleabbrev>Get specific role</titleabbrev>
++++
experimental[] Retrieve a specific role.
[[role-management-specific-api-get-prereqs]]
==== Prerequisite
To use the get specific role API, you must have the `manage_security` cluster privilege.
[[role-management-specific-api-retrieve-all-request-body]]
===== Request
`GET <kibana host>:<port>/api/security/role/my_restricted_kibana_role`
[[role-management-specific-api-retrieve-all-response-codes]]
==== Response code
`200`::
Indicates a successful call.
[[role-management-specific-api-retrieve-all-example]]
===== Example
The API returns the following:
[source,sh]
--------------------------------------------------
{
"name": "my_restricted_kibana_role",
"description": "My restricted kibana role description",
"metadata" : {
"version" : 1
},
"transient_metadata": {
"enabled": true
},
"elasticsearch": {
"cluster": [ ],
"indices": [ ],
"run_as": [ ]
},
"kibana": [
{
"base": [
"read"
],
"feature": {},
"spaces": [
"marketing"
]
},
{
"base": [],
"feature": {
"discover": [
"all"
],
"visualize": [
"all"
],
"dashboard": [
"all"
],
"dev_tools": [
"read"
],
"advancedSettings": [
"read"
],
"indexPatterns": [
"read"
],
"graph": [
"all"
],
"apm": [
"read"
],
"maps": [
"read"
],
"canvas": [
"read"
],
"infrastructure": [
"all"
],
"logs": [
"all"
],
"uptime": [
"all"
]
},
"spaces": [
"sales",
"default"
]
}
]
}
--------------------------------------------------

377
docs/api/role-management/put-bulk.asciidoc
View file

@ -1,377 +0,0 @@
[[role-management-api-put-bulk]]
=== Bulk create or update roles API
++++
<titleabbrev>Bulk create or update roles API</titleabbrev>
++++
preview::["This functionality is in technical preview, and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."]
experimental[] Create new {kib} roles, or update the attributes of an existing roles. {kib} roles are stored in the
{es} native realm.
[[role-management-api-put-bulk-request]]
==== Request
`POST <kibana host>:<port>/api/security/roles`
[[role-management-api-put-bulk-prereqs]]
==== Prerequisite
To use the bulk create or update roles API, you must have the `manage_security` cluster privilege.
[role="child_attributes"]
[[role-management-api-bulk-response-body]]
==== Request body
`roles`::
(object) Object that specifies the roles to add as a role name to role map.
`<role_name>` (required):: (string) The role name.
`description`::
(Optional, string) Description for the role.
`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`, `remote_indices`, `remote_cluster`, and `run_as`. For more information, see
{ref}/defining-roles.html[Defining roles].
`kibana`::
(list) Objects that specify the <<kibana-privileges, Kibana privileges>> for the role.
+
.Properties of `kibana`
[%collapsible%open]
=====
`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-get, 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-bulk-put-response-codes]]
==== Response code
`200`::
Indicates a successful call.
==== Examples
Grant access to various features in all spaces:
[source,sh]
--------------------------------------------------
$ curl -X POST api/security/roles
{
"roles": {
"my_kibana_role_1": {
"description": "my_kibana_role_1_description",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"visualize": ["all"],
"dashboard": ["all"],
"dev_tools": ["read"],
"advancedSettings": ["read"],
"indexPatterns": ["read"],
"graph": ["all"],
"apm": ["read"],
"maps": ["read"],
"canvas": ["read"],
"infrastructure": ["all"],
"logs": ["all"],
"uptime": ["all"]
},
"spaces": ["*"]
}
]
},
"my_kibana_role_2": {
"description": "my_kibana_role_2_description",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"visualize": ["all"],
"dashboard": ["all"],
"dev_tools": ["read"],
"logs": ["all"],
"uptime": ["all"]
},
"spaces": ["*"]
}
]
}
}
}
--------------------------------------------------
// KIBANA
Grant dashboard-only access to only the Marketing space for `my_kibana_role_1` and dashboard-only access to only Sales space for `my_kibana_role_2`:
[source,sh]
--------------------------------------------------
$ curl -X POST api/security/roles
{
"roles": {
"my_kibana_role_1": {
"description": "Grants dashboard-only access to only the Marketing space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"dashboard": ["read"]
},
"spaces": ["marketing"]
}
]
},
"my_kibana_role_2": {
"description": "Grants dashboard-only access to only the Sales space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"dashboard": ["read"]
},
"spaces": ["sales"]
}
]
}
}
}
--------------------------------------------------
// KIBANA
Grant full access to all features in the Default space for `my_kibana_role_1` and `my_kibana_role_2`:
[source,sh]
--------------------------------------------------
$ curl -X POST api/security/roles
{
"roles": {
"my_kibana_role_1": {
"description": "Grants full access to all features in the Default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": ["all"],
"feature": {},
"spaces": ["default"]
}
]
},
"my_kibana_role_2": {
"description": "Grants full access to all features in the Default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": ["all"],
"feature": {},
"spaces": ["default"]
}
]
}
}
}
--------------------------------------------------
// KIBANA
Grant different access to different spaces:
[source,sh]
--------------------------------------------------
$ curl -X POST api/security/roles
{
"roles": {
"my_kibana_role_1": {
"description": "Grants full access to discover and dashboard features in the default space. Grants read access in the marketing, and sales spaces.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"dashboard": ["all"]
},
"spaces": ["default"]
},
{
"base": ["read"],
"spaces": ["marketing", "sales"]
}
]
},
"my_kibana_role_2": {
"description": "Grants full access to discover and dashboard features in the default space. Grants read access in the marketing space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [],
"indices": []
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"dashboard": ["all"]
},
"spaces": ["default"]
},
{
"base": ["read"],
"spaces": ["marketing"]
}
]
}
}
}
--------------------------------------------------
// KIBANA
Grant access to {kib} and {es}:
[source,sh]
--------------------------------------------------
$ curl -X POST api/security/roles
{
"roles": {
"my_kibana_role_1": {
"description": "Grants all cluster privileges and full access to index1 and index2. Grants full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grants all Kibana privileges in the default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": ["all"],
"indices": [
{
"names": ["index1", "index2"],
"privileges": ["all"]
}
],
"remote_indices": [
{
"clusters": ["remote_cluster1"],
"names": ["remote_index1", "remote_index2"],
"privileges": ["all"]
}
],
"remote_cluster": [
{
"clusters": ["remote_cluster1"],
"privileges": ["monitor_enrich"]
}
]
},
"kibana": [
{
"base": ["all"],
"feature": {},
"spaces": ["default"]
}
]
},
"my_kibana_role_2": {
"description": "Grants all cluster privileges and full access to index1. Grants full access to remote_index1, and the monitor_enrich cluster privilege on remote_cluster1. Grants all Kibana privileges in the default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": ["all"],
"indices": [
{
"names": ["index1"],
"privileges": ["all"]
}
],
"remote_indices": [
{
"clusters": ["remote_cluster1"],
"names": ["remote_index1"],
"privileges": ["all"]
}
],
"remote_cluster": [
{
"clusters": ["remote_cluster1"],
"privileges": ["monitor_enrich"]
}
]
},
"kibana": [
{
"base": ["all"],
"feature": {},
"spaces": ["default"]
}
]
}
}
}
--------------------------------------------------
// KIBANA

238
docs/api/role-management/put.asciidoc
View file

@ -1,238 +0,0 @@
[[role-management-api-put]]
=== Create or update role API
++++
<titleabbrev>Create or update role</titleabbrev>
++++
experimental[] Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the
{es} native realm.
[[role-management-api-put-request]]
==== Request
`PUT <kibana host>:<port>/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="child_attributes"]
[[role-management-api-response-body]]
==== Request body
`description`::
(Optional, string) Description for the role.
`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`, `remote_indices`, `remote_cluster`, and `run_as`. For more information, see
{ref}/defining-roles.html[Defining roles].
`kibana`::
(list) Objects that specify the <<kibana-privileges, Kibana privileges>> for the role.
+
.Properties of `kibana`
[%collapsible%open]
=====
`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-get, 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-query-params]]
==== Query parameters
`createOnly`::
(Optional, boolean) When `true`, will prevent overwriting the role if it already exists.
[[role-management-api-put-response-codes]]
==== Response code
`204`::
Indicates a successful call.
`409`::
When `createOnly` is true, indicates a conflict with an existing role.
==== Examples
Grant access to various features in all spaces:
[source,sh]
--------------------------------------------------
$ curl -X PUT api/security/role/my_kibana_role
{
"description": "my_kibana_role_description",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [ ],
"indices": [ ]
},
"kibana": [
{
"base": [ ],
"feature": {
"discover": [ "all" ],
"visualize": [ "all" ],
"dashboard": [ "all" ],
"dev_tools": [ "read" ],
"advancedSettings": [ "read" ],
"indexPatterns": [ "read" ],
"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,sh]
--------------------------------------------------
$ curl -X PUT api/security/role/my_kibana_role
{
"description": "Grants dashboard-only access to only the Marketing space.",
"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,sh]
--------------------------------------------------
$ curl -X PUT api/security/role/my_kibana_role
{
"description": "Grants full access to all features in the Default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [ ],
"indices": [ ]
},
"kibana": [
{
"base": [ "all" ],
"feature": { },
"spaces": [ "default" ]
}
]
}
--------------------------------------------------
// KIBANA
Grant different access to different spaces:
[source,sh]
--------------------------------------------------
$ curl -X PUT api/security/role/my_kibana_role
{
"description": "Grants full access to discover and dashboard features in the default space. Grants read access in the marketing, and sales spaces.",
"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 {es}:
[source,sh]
--------------------------------------------------
$ curl -X PUT api/security/role/my_kibana_role
{
"description": "Grants all cluster privileges and full access to index1 and index2. Grants full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grants all Kibana privileges in the default space.",
"metadata": {
"version": 1
},
"elasticsearch": {
"cluster": [ "all" ],
"indices": [
{
"names": [ "index1", "index2" ],
"privileges": [ "all" ]
}
],
"remote_indices": [
{
"clusters": [ "remote_cluster1" ],
"names": [ "remote_index1", "remote_index2" ],
"privileges": [ "all" ]
}
],
"remote_cluster": [
{
"clusters": [ "remote_cluster1" ],
"privileges": [ "monitor_enrich" ]
}
]
},
"kibana": [
{
"base": [ "all" ],
"feature": { },
"spaces": [ "default" ]
}
]
}
--------------------------------------------------
// KIBANA

2
docs/developer/architecture/security/rbac.asciidoc
View file

@ -77,7 +77,7 @@ The application is created by concatenating the prefix of `kibana-` with the val
}
----------------------------------
Roles that grant <<kibana-privileges>> should be managed using the <<role-management-api>> or the *Management -> Security -> Roles* page, not directly using the {es} {ref}/security-api.html#security-role-apis[role management API]. This role can then be assigned to users using the {es}
Roles that grant <<kibana-privileges>> should be managed using the {api-kibana}/group/endpoint-roles[role APIs] or the *Management -> Security -> Roles* page, not directly using the {es} {ref}/security-api.html#security-role-apis[role management API]. This role can then be assigned to users using the {es}
{ref}/security-api.html#security-user-apis[user management APIs].
[[development-rbac-authorization]]

5
docs/management/watcher-ui/index.asciidoc
View file

@ -39,9 +39,8 @@ and either of these Watcher roles:
* `watcher_admin`. You can perform all Watcher actions, including create and edit watches.
* `watcher_user`. You can view watches, but not create or edit them.
To manage roles, open the main menu, then click *Stack Management > Roles*, or use the
<<role-management-api, Kibana Role Management API>>. Watches are shared between
all users with the same role.
To manage roles, open the main menu, then click *Stack Management > Roles*, or use the {api-kibana}/group/endpoint-roles[role APIs].
Watches are shared between all users with the same role.
NOTE: If you are creating a threshold watch, you must also have the `view_index_metadata` index privilege. See
{ref}/index-mgmt.html[Index management] for detailed information.

26
docs/redirects.asciidoc
View file

@ -1196,4 +1196,28 @@ Refer to {api-kibana}/group/endpoint-spaces[spaces APIs].
[role="exclude",id="spaces-api-update-objects-spaces"]
== Update saved objects spaces API
Refer to {api-kibana}/group/endpoint-spaces[spaces APIs].
Refer to {api-kibana}/group/endpoint-spaces[spaces APIs].
[role="exclude",id="role-management-api-delete]
== Delete role API
Refer to {api-kibana}/group/endpoint-roles[role APIs].
[role="exclude",id="role-management-api-get"]
== Get all {kib} roles API
Refer to {api-kibana}/group/endpoint-roles[role APIs].
[role="exclude",id="role-management-specific-api-get"]
== Get specific role API
Refer to {api-kibana}/group/endpoint-roles[role APIs].
[role="exclude",id="role-management-api-put-bulk"]
== Bulk create or update roles API
Refer to {api-kibana}/group/endpoint-roles[role APIs].
[role="exclude",id="role-management-api-put"]
== Create or update role API
Refer to {api-kibana}/group/endpoint-roles[role APIs].

5
docs/setup/configuring-reporting.asciidoc
View file

@ -99,9 +99,10 @@ Granting the privilege to generate reports also grants the user the privilege to
[float]
[[reporting-roles-user-api]]
==== Grant access with the role API
With <<grant-user-access, {kib} application privileges>> enabled in Reporting, you can also use the {ref}/security-api-put-role.html[role API] to grant access to the {report-features}, using *All* privileges, or sub-feature privileges.
With <<grant-user-access,{kib} application privileges>> enabled in Reporting, you can also use the {api-kibana}/group/endpoint-roles[role APIs] to grant access to the {report-features}, using *All* privileges, or sub-feature privileges.
NOTE: This API request needs to be run against the <<api,Kibana API endpoint>>.
NOTE: This link:https://www.elastic.co/guide/en/kibana/current/role-management-api-put.html[API request] needs to be executed against the link:https://www.elastic.co/guide/en/kibana/current/api.html[Kibana API endpoint].
[source, sh]
---------------------------------------------------------------
PUT <kibana host>:<port>/api/security/role/custom_reporting_user

4
docs/user/introduction.asciidoc
View file

@ -193,8 +193,8 @@ or even give users their very own private space. For example, power users might
have privileges to create and edit visualizations and dashboards,
while analysts or executives might have *Dashboard* and *Canvas* with read-only privileges.
{kib}’s role management interface allows you to describe these various access
levels, or you can automate role creation via our <<role-management-api,API>>.
The {kib} role management interface allows you to describe these various access
levels, or you can automate role creation by using {api-kibana}/group/endpoint-roles[role APIs].
[role="screenshot"]
image::spaces/images/spaces-roles.png[{kib privileges}]

2
docs/user/security/api-keys/index.asciidoc
View file

@ -28,7 +28,7 @@ image:images/api-keys.png["API Keys UI"]
* To create or update a *cross-cluster API key*, you must have the `manage_security` privilege and an Enterprise license.
* To have a read-only view on the API keys, you must have access to the page and the `read_security` cluster privilege.
To manage roles, open the main menu, then click *Stack Management > Security > Roles*, or use the <<role-management-api, {kib} Role Management API>>.
To manage roles, open the main menu, then click *Stack Management > Security > Roles*, or use the {api-kibana}/group/endpoint-roles[role APIs].
[float]
[[create-api-key]]

19
docs/user/security/authorization/kibana-privileges.asciidoc
View file

@ -1,22 +1,21 @@
[role="xpack"]
[[kibana-privileges]]
=== {kib} privileges
= {kib} privileges
{kib} privileges grant users access to features within {kib}. Roles have privileges to determine whether users have write or read access.
==== Base privileges
== Base privileges
Assigning a base privilege grants access to all {kib} features, such as *Discover*, *Dashboard*, *Visualize Library*, and *Canvas*.
[[kibana-privileges-all]]
`all`:: Grants full read-write access.
`read`:: Grants read-only access.
===== Assigning base privileges
=== Assigning base privileges
From the role management screen:
[role="screenshot"]
image::security/images/assign-base-privilege.png[Assign base privilege]
From the <<role-management-api-put, role management API>>:
Using the {api-kibana}/group/endpoint-roles[role APIs]:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
@ -37,23 +36,23 @@ PUT /api/security/role/my_kibana_role
[[kibana-feature-privileges]]
==== Feature privileges
== Feature privileges
Assigning a feature privilege grants access to a specific feature.
`all`:: Grants full read-write access.
`read`:: Grants read-only access.
===== Sub-feature privileges
=== Sub-feature privileges
Some features allow for finer access control than the `all` and `read` privileges.
This additional level of control is a https://www.elastic.co/subscriptions[subscription feature].
This additional level of control is a {subscriptions}[subscription feature].
===== Assigning feature privileges
=== Assigning feature privileges
From the role management screen:
[role="screenshot"]
image::security/images/assign-subfeature-privilege.png[Assign feature privilege]
From the <<role-management-api-put, role management API>>:
Using the {api-kibana}/group/endpoint-roles[role APIs]:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role

4
docs/user/security/index.asciidoc
View file

@ -30,7 +30,7 @@ authentication and built-in users, see
=== Roles
To manage roles, open the main menu, then click *Stack Management > Roles*, or use
the <<role-management-api>>. For more information on configuring roles for {kib}, see <<xpack-security-authorization, Granting access to {kib}>>.
the {api-kibana}/group/endpoint-roles[role APIs]. For more information on configuring roles for {kib}, see <<xpack-security-authorization,Granting access to {kib}>>.
For a more holistic overview of configuring roles for the entire stack,
see {ref}/authorization.html[User authorization].
@ -43,7 +43,7 @@ cause Kibana's authorization to behave unexpectedly.
============================================================================
include::authorization/index.asciidoc[]
include::authorization/kibana-privileges.asciidoc[]
include::authorization/kibana-privileges.asciidoc[leveloffset=+2]
include::api-keys/index.asciidoc[]
include::role-mappings/index.asciidoc[]
include::fips-140-2.asciidoc[]

76
oas_docs/bundle.json
View file

@ -6192,6 +6192,7 @@
}
},
{
"description": "If `true` and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.",
"in": "query",
"name": "replaceDeprecatedPrivileges",
"required": false,
@ -6200,7 +6201,11 @@
}
}
],
"responses": {},
"responses": {
"200": {
"description": "Indicates a successful call."
}
},
"summary": "Get all roles",
"tags": [
"roles"
@ -6243,7 +6248,11 @@
}
}
],
"responses": {},
"responses": {
"204": {
"description": "Indicates a successful call."
}
},
"summary": "Delete a role",
"tags": [
"roles"
@ -6265,6 +6274,7 @@
}
},
{
"description": "The role name.",
"in": "path",
"name": "name",
"required": true,
@ -6274,6 +6284,7 @@
}
},
{
"description": "If `true` and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.",
"in": "query",
"name": "replaceDeprecatedPrivileges",
"required": false,
@ -6282,13 +6293,18 @@
}
}
],
"responses": {},
"responses": {
"200": {
"description": "Indicates a successful call."
}
},
"summary": "Get a role",
"tags": [
"roles"
]
},
"put": {
"description": "Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.",
"operationId": "%2Fapi%2Fsecurity%2Frole%2F%7Bname%7D#2",
"parameters": [
{
@ -6314,6 +6330,7 @@
}
},
{
"description": "The role name.",
"in": "path",
"name": "name",
"required": true,
@ -6324,6 +6341,7 @@
}
},
{
"description": "When true, a role is not overwritten if it already exists.",
"in": "query",
"name": "createOnly",
"required": false,
@ -6340,6 +6358,7 @@
"additionalProperties": false,
"properties": {
"description": {
"description": "A description for the role.",
"maxLength": 2048,
"type": "string"
},
@ -6348,6 +6367,7 @@
"properties": {
"cluster": {
"items": {
"description": "Cluster privileges that define the cluster level actions that users can perform.",
"type": "string"
},
"type": "array"
@ -6357,11 +6377,13 @@
"additionalProperties": false,
"properties": {
"allow_restricted_indices": {
"description": "Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.",
"type": "boolean"
},
"field_security": {
"additionalProperties": {
"items": {
"description": "The document fields that the role members have read access to.",
"type": "string"
},
"type": "array"
@ -6370,6 +6392,7 @@
},
"names": {
"items": {
"description": "The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).",
"type": "string"
},
"minItems": 1,
@ -6377,12 +6400,14 @@
},
"privileges": {
"items": {
"description": "The index level privileges that the role members have for the data streams and indices.",
"type": "string"
},
"minItems": 1,
"type": "array"
},
"query": {
"description": "A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.",
"type": "string"
}
},
@ -6400,6 +6425,7 @@
"properties": {
"clusters": {
"items": {
"description": "A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.",
"type": "string"
},
"minItems": 1,
@ -6407,6 +6433,7 @@
},
"privileges": {
"items": {
"description": "The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.",
"type": "string"
},
"minItems": 1,
@ -6426,10 +6453,12 @@
"additionalProperties": false,
"properties": {
"allow_restricted_indices": {
"description": "Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.",
"type": "boolean"
},
"clusters": {
"items": {
"description": "A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.",
"type": "string"
},
"minItems": 1,
@ -6438,6 +6467,7 @@
"field_security": {
"additionalProperties": {
"items": {
"description": "The document fields that the role members have read access to.",
"type": "string"
},
"type": "array"
@ -6446,6 +6476,7 @@
},
"names": {
"items": {
"description": "A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).",
"type": "string"
},
"minItems": 1,
@ -6453,12 +6484,14 @@
},
"privileges": {
"items": {
"description": "The index level privileges that role members have for the specified indices.",
"type": "string"
},
"minItems": 1,
"type": "array"
},
"query": {
"description": "A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members. ",
"type": "string"
}
},
@ -6473,6 +6506,7 @@
},
"run_as": {
"items": {
"description": "A user name that the role member can impersonate.",
"type": "string"
},
"type": "array"
@ -6507,12 +6541,14 @@
"oneOf": [
{
"items": {
"description": "A base privilege that grants applies to all spaces.",
"type": "string"
},
"type": "array"
},
{
"items": {
"description": "A base privilege that applies to specific spaces.",
"type": "string"
},
"type": "array"
@ -6522,6 +6558,7 @@
"feature": {
"additionalProperties": {
"items": {
"description": "The privileges that the role member has for the feature.",
"type": "string"
},
"type": "array"
@ -6543,6 +6580,7 @@
},
{
"items": {
"description": "A space that the privilege applies to.",
"type": "string"
},
"type": "array"
@ -6573,7 +6611,11 @@
}
}
},
"responses": {},
"responses": {
"204": {
"description": "Indicates a successful call."
}
},
"summary": "Create or update a role",
"tags": [
"roles"
@ -6618,6 +6660,7 @@
"additionalProperties": false,
"properties": {
"description": {
"description": "A description for the role.",
"maxLength": 2048,
"type": "string"
},
@ -6626,6 +6669,7 @@
"properties": {
"cluster": {
"items": {
"description": "Cluster privileges that define the cluster level actions that users can perform.",
"type": "string"
},
"type": "array"
@ -6635,11 +6679,13 @@
"additionalProperties": false,
"properties": {
"allow_restricted_indices": {
"description": "Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.",
"type": "boolean"
},
"field_security": {
"additionalProperties": {
"items": {
"description": "The document fields that the role members have read access to.",
"type": "string"
},
"type": "array"
@ -6648,6 +6694,7 @@
},
"names": {
"items": {
"description": "The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).",
"type": "string"
},
"minItems": 1,
@ -6655,12 +6702,14 @@
},
"privileges": {
"items": {
"description": "The index level privileges that the role members have for the data streams and indices.",
"type": "string"
},
"minItems": 1,
"type": "array"
},
"query": {
"description": "A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.",
"type": "string"
}
},
@ -6678,6 +6727,7 @@
"properties": {
"clusters": {
"items": {
"description": "A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.",
"type": "string"
},
"minItems": 1,
@ -6685,6 +6735,7 @@
},
"privileges": {
"items": {
"description": "The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.",
"type": "string"
},
"minItems": 1,
@ -6704,10 +6755,12 @@
"additionalProperties": false,
"properties": {
"allow_restricted_indices": {
"description": "Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.",
"type": "boolean"
},
"clusters": {
"items": {
"description": "A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.",
"type": "string"
},
"minItems": 1,
@ -6716,6 +6769,7 @@
"field_security": {
"additionalProperties": {
"items": {
"description": "The document fields that the role members have read access to.",
"type": "string"
},
"type": "array"
@ -6724,6 +6778,7 @@
},
"names": {
"items": {
"description": "A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).",
"type": "string"
},
"minItems": 1,
@ -6731,12 +6786,14 @@
},
"privileges": {
"items": {
"description": "The index level privileges that role members have for the specified indices.",
"type": "string"
},
"minItems": 1,
"type": "array"
},
"query": {
"description": "A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members. ",
"type": "string"
}
},
@ -6751,6 +6808,7 @@
},
"run_as": {
"items": {
"description": "A user name that the role member can impersonate.",
"type": "string"
},
"type": "array"
@ -6785,12 +6843,14 @@
"oneOf": [
{
"items": {
"description": "A base privilege that grants applies to all spaces.",
"type": "string"
},
"type": "array"
},
{
"items": {
"description": "A base privilege that applies to specific spaces.",
"type": "string"
},
"type": "array"
@ -6800,6 +6860,7 @@
"feature": {
"additionalProperties": {
"items": {
"description": "The privileges that the role member has for the feature.",
"type": "string"
},
"type": "array"
@ -6821,6 +6882,7 @@
},
{
"items": {
"description": "A space that the privilege applies to.",
"type": "string"
},
"type": "array"
@ -6859,7 +6921,11 @@
}
}
},
"responses": {},
"responses": {
"200": {
"description": "Indicates a successful call."
}
},
"summary": "Create or update roles",
"tags": [
"roles"

6637
oas_docs/bundle.serverless.json
View file

File diff suppressed because it is too large Load diff

23
oas_docs/examples/create_role_request1.yaml Normal file
View file

@ -0,0 +1,23 @@
summary: Feature privileges in multiple spaces
description: Grant access to various features in some spaces.
value:
description: Grant full access to discover and dashboard features in the default space. Grant read access in the marketing, and sales spaces.
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base: []
feature:
discover:
- all
dashboard:
- all
spaces:
- default
- base:
- read
spaces:
- marketing
- sales

16
oas_docs/examples/create_role_request2.yaml Normal file
View file

@ -0,0 +1,16 @@
summary: Dashboard privileges in a space
description: Grant access to dashboard features in a Marketing space.
value:
description: Grant dashboard access in the Marketing space.
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base: []
feature:
dashboard:
- read
spaces:
- marketing

14
oas_docs/examples/create_role_request3.yaml Normal file
View file

@ -0,0 +1,14 @@
summary: Feature privileges in a space
description: Grant full access to all features in the default space.
value:
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base:
- all
feature: { }
spaces:
- default

34
oas_docs/examples/create_role_request4.yaml Normal file
View file

@ -0,0 +1,34 @@
summary: Elasticsearch and Kibana feature privileges
description: Grant Elasticsearch and Kibana feature privileges.
value:
description: Grant all cluster privileges and full access to index1 and index2. Grant full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grant all Kibana privileges in the default space.
metadata:
version: 1
elasticsearch:
cluster:
- all
indices:
- names:
- index1
- index2
privileges:
- all
remote_indices:
- clusters:
- remote_cluster1
names:
- remote_index1
- remote_index2
privileges:
- all
remote_cluster:
- clusters:
- remote_cluster1
privileges:
- monitor_enrich
kibana:
- base:
- all
feature: { }
spaces:
- default

41
oas_docs/examples/get_role_response1.yaml Normal file
View file

@ -0,0 +1,41 @@
summary: Get role details
value:
name: my_kibana_role
description: Grants all cluster privileges and full access to index1 and index2. Grants full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grants all Kibana privileges in the default space.
metadata:
version: 1
transient_metadata:
enabled: true
elasticsearch:
cluster:
- all
remote_cluster:
- privileges:
- monitor_enrich
clusters:
- remote_cluster1
indices:
- names:
- index1
- index2
privileges:
- all
allow_restricted_indices: false
remote_indices:
- names:
- remote_index1
- remote_index2
privileges:
- all
allow_restricted_indices: false
clusters:
- remote_cluster1
run_as: []
kibana:
- base:
- all
feature: {}
spaces:
- default
_transform_error: []
_unrecognized_applications: []

39
oas_docs/examples/get_roles_response1.yaml Normal file
View file

@ -0,0 +1,39 @@
summary: Get all role details
value:
- name: my_kibana_role
description: My kibana role description
metadata:
version: 1
transient_metadata:
enabled: true
elasticsearch:
indices: []
cluster: []
run_as: []
kibana:
- base:
- all
feature: {}
spaces:
- "*"
- name: my_admin_role
description: My admin role description
metadata:
version: 1
transient_metadata:
enabled: true
elasticsearch:
cluster:
- all
indices:
- names:
- index1
- index2
privileges:
- all
field_security:
grant:
- title
- body
query: '{\"match\": {\"title\": \"foo\"}}'
kibana: []

3
oas_docs/makefile
View file

@ -14,8 +14,7 @@
# permission is obtained from Elasticsearch B.V.
.PHONY: api-docs
api-docs: ## Generate Serverless and ESS Kibana OpenAPI bundles with kbn-openapi-bundler
@node scripts/merge_serverless_oas.js
api-docs: ## Generate ESS Kibana OpenAPI bundles with kbn-openapi-bundler
@node scripts/merge_ess_oas.js
.PHONY: api-docs-stateful

33624
oas_docs/output/kibana.serverless.yaml
View file

File diff suppressed because it is too large Load diff

230
oas_docs/output/kibana.yaml
View file

@ -20201,12 +20201,18 @@ paths:
enum:
- '2023-10-31'
type: string
- in: query
- description: >-
If `true` and the response contains any privileges that are
associated with deprecated features, they are omitted in favor of
details about the appropriate replacement feature privileges.
in: query
name: replaceDeprecatedPrivileges
required: false
schema:
type: boolean
responses: {}
responses:
'200':
description: Indicates a successful call.
summary: Get all roles
tags:
- roles
@ -20235,7 +20241,9 @@ paths:
schema:
minLength: 1
type: string
responses: {}
responses:
'204':
description: Indicates a successful call.
summary: Delete a role
tags:
- roles
@ -20250,22 +20258,32 @@ paths:
enum:
- '2023-10-31'
type: string
- in: path
- description: The role name.
in: path
name: name
required: true
schema:
minLength: 1
type: string
- in: query
- description: >-
If `true` and the response contains any privileges that are
associated with deprecated features, they are omitted in favor of
details about the appropriate replacement feature privileges.
in: query
name: replaceDeprecatedPrivileges
required: false
schema:
type: boolean
responses: {}
responses:
'200':
description: Indicates a successful call.
summary: Get a role
tags:
- roles
put:
description: >-
Create a new Kibana role or update the attributes of an existing role.
Kibana roles are stored in the Elasticsearch native realm.
operationId: '%2Fapi%2Fsecurity%2Frole%2F%7Bname%7D#2'
parameters:
- description: The version of the API to use
@ -20283,14 +20301,16 @@ paths:
schema:
example: 'true'
type: string
- in: path
- description: The role name.
in: path
name: name
required: true
schema:
maxLength: 1024
minLength: 1
type: string
- in: query
- description: 'When true, a role is not overwritten if it already exists.'
in: query
name: createOnly
required: false
schema:
@ -20304,6 +20324,7 @@ paths:
type: object
properties:
description:
description: A description for the role.
maxLength: 2048
type: string
elasticsearch:
@ -20312,6 +20333,9 @@ paths:
properties:
cluster:
items:
description: >-
Cluster privileges that define the cluster level
actions that users can perform.
type: string
type: array
indices:
@ -20320,24 +20344,55 @@ paths:
type: object
properties:
allow_restricted_indices:
description: >-
Restricted indices are a special category of
indices that are used internally to store
configuration data and should not be directly
accessed. Only internal system roles should
normally grant privileges over the restricted
indices. Toggling this flag is very strongly
discouraged because it could effectively grant
unrestricted operations on critical data, making
the entire system unstable or leaking sensitive
information. If for administrative purposes you
need to create a role with privileges covering
restricted indices, however, you can set this
property to true. In that case, the names field
covers the restricted indices too.
type: boolean
field_security:
additionalProperties:
items:
description: >-
The document fields that the role members have
read access to.
type: string
type: array
type: object
names:
items:
description: >-
The data streams, indices, and aliases to which
the permissions in this entry apply. It supports
wildcards (*).
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The index level privileges that the role members
have for the data streams and indices.
type: string
minItems: 1
type: array
query:
description: >-
A search query that defines the documents the role
members have read access to. A document within the
specified data streams and indices must match this
query in order for it to be accessible by the role
members.
type: string
required:
- names
@ -20350,11 +20405,19 @@ paths:
properties:
clusters:
items:
description: >-
A list of remote cluster aliases. It supports
literal strings as well as wildcards and regular
expressions.
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The cluster level privileges for the remote
cluster. The allowed values are a subset of the
cluster privileges.
type: string
minItems: 1
type: array
@ -20368,29 +20431,64 @@ paths:
type: object
properties:
allow_restricted_indices:
description: >-
Restricted indices are a special category of
indices that are used internally to store
configuration data and should not be directly
accessed. Only internal system roles should
normally grant privileges over the restricted
indices. Toggling this flag is very strongly
discouraged because it could effectively grant
unrestricted operations on critical data, making
the entire system unstable or leaking sensitive
information. If for administrative purposes you
need to create a role with privileges covering
restricted indices, however, you can set this
property to true. In that case, the names field
will cover the restricted indices too.
type: boolean
clusters:
items:
description: >-
A list of remote cluster aliases. It supports
literal strings as well as wildcards and regular
expressions.
type: string
minItems: 1
type: array
field_security:
additionalProperties:
items:
description: >-
The document fields that the role members have
read access to.
type: string
type: array
type: object
names:
items:
description: >-
A list of remote aliases, data streams, or
indices to which the permissions apply. It
supports wildcards (*).
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The index level privileges that role members
have for the specified indices.
type: string
minItems: 1
type: array
query:
description: >-
A search query that defines the documents the role
members have read access to. A document within the
specified data streams and indices must match this
query in order for it to be accessible by the role
members.
type: string
required:
- clusters
@ -20399,6 +20497,7 @@ paths:
type: array
run_as:
items:
description: A user name that the role member can impersonate.
type: string
type: array
kibana:
@ -20417,14 +20516,23 @@ paths:
nullable: true
oneOf:
- items:
description: >-
A base privilege that grants applies to all
spaces.
type: string
type: array
- items:
description: >-
A base privilege that applies to specific
spaces.
type: string
type: array
feature:
additionalProperties:
items:
description: >-
The privileges that the role member has for the
feature.
type: string
type: array
type: object
@ -20438,6 +20546,7 @@ paths:
minItems: 1
type: array
- items:
description: A space that the privilege applies to.
type: string
type: array
default:
@ -20450,7 +20559,9 @@ paths:
type: object
required:
- elasticsearch
responses: {}
responses:
'204':
description: Indicates a successful call.
summary: Create or update a role
tags:
- roles
@ -20486,6 +20597,7 @@ paths:
type: object
properties:
description:
description: A description for the role.
maxLength: 2048
type: string
elasticsearch:
@ -20494,6 +20606,9 @@ paths:
properties:
cluster:
items:
description: >-
Cluster privileges that define the cluster level
actions that users can perform.
type: string
type: array
indices:
@ -20502,24 +20617,58 @@ paths:
type: object
properties:
allow_restricted_indices:
description: >-
Restricted indices are a special category of
indices that are used internally to store
configuration data and should not be
directly accessed. Only internal system
roles should normally grant privileges over
the restricted indices. Toggling this flag
is very strongly discouraged because it
could effectively grant unrestricted
operations on critical data, making the
entire system unstable or leaking sensitive
information. If for administrative purposes
you need to create a role with privileges
covering restricted indices, however, you
can set this property to true. In that case,
the names field covers the restricted
indices too.
type: boolean
field_security:
additionalProperties:
items:
description: >-
The document fields that the role
members have read access to.
type: string
type: array
type: object
names:
items:
description: >-
The data streams, indices, and aliases to
which the permissions in this entry apply.
It supports wildcards (*).
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The index level privileges that the role
members have for the data streams and
indices.
type: string
minItems: 1
type: array
query:
description: >-
A search query that defines the documents
the role members have read access to. A
document within the specified data streams
and indices must match this query in order
for it to be accessible by the role members.
type: string
required:
- names
@ -20532,11 +20681,19 @@ paths:
properties:
clusters:
items:
description: >-
A list of remote cluster aliases. It
supports literal strings as well as
wildcards and regular expressions.
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The cluster level privileges for the
remote cluster. The allowed values are a
subset of the cluster privileges.
type: string
minItems: 1
type: array
@ -20550,29 +20707,67 @@ paths:
type: object
properties:
allow_restricted_indices:
description: >-
Restricted indices are a special category of
indices that are used internally to store
configuration data and should not be
directly accessed. Only internal system
roles should normally grant privileges over
the restricted indices. Toggling this flag
is very strongly discouraged because it
could effectively grant unrestricted
operations on critical data, making the
entire system unstable or leaking sensitive
information. If for administrative purposes
you need to create a role with privileges
covering restricted indices, however, you
can set this property to true. In that case,
the names field will cover the restricted
indices too.
type: boolean
clusters:
items:
description: >-
A list of remote cluster aliases. It
supports literal strings as well as
wildcards and regular expressions.
type: string
minItems: 1
type: array
field_security:
additionalProperties:
items:
description: >-
The document fields that the role
members have read access to.
type: string
type: array
type: object
names:
items:
description: >-
A list of remote aliases, data streams, or
indices to which the permissions apply. It
supports wildcards (*).
type: string
minItems: 1
type: array
privileges:
items:
description: >-
The index level privileges that role
members have for the specified indices.
type: string
minItems: 1
type: array
query:
description: >-
A search query that defines the documents
the role members have read access to. A
document within the specified data streams
and indices must match this query in order
for it to be accessible by the role
members.
type: string
required:
- clusters
@ -20581,6 +20776,9 @@ paths:
type: array
run_as:
items:
description: >-
A user name that the role member can
impersonate.
type: string
type: array
kibana:
@ -20599,14 +20797,23 @@ paths:
nullable: true
oneOf:
- items:
description: >-
A base privilege that grants applies to
all spaces.
type: string
type: array
- items:
description: >-
A base privilege that applies to specific
spaces.
type: string
type: array
feature:
additionalProperties:
items:
description: >-
The privileges that the role member has for
the feature.
type: string
type: array
type: object
@ -20620,6 +20827,7 @@ paths:
minItems: 1
type: array
- items:
description: A space that the privilege applies to.
type: string
type: array
default:
@ -20635,7 +20843,9 @@ paths:
type: object
required:
- roles
responses: {}
responses:
'200':
description: Indicates a successful call.
summary: Create or update roles
tags:
- roles

4
oas_docs/overlays/kibana.overlays.serverless.yaml
View file

@ -30,7 +30,7 @@ actions:
Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
externalDocs:
description: Alerting documentation
url: https://www.elastic.co/docs/current/serverless/rules
url: https://www.elastic.co/docs/8.x/serverless/rules
x-displayName: "Alerting"
- target: '$.tags[?(@.name=="connectors")]'
description: Change tag description and displayName
@ -40,7 +40,7 @@ actions:
Alerting rules can use connectors to run actions when rule conditions are met.
externalDocs:
description: Connector documentation
url: https://www.elastic.co/docs/current/serverless/action-connectors
url: https://www.elastic.co/docs/8.x/serverless/action-connectors
x-displayName: "Connectors"
- target: '$.tags[?(@.name=="data views")]'
description: Change displayName

49
oas_docs/overlays/kibana.overlays.yaml
View file

@ -23,7 +23,7 @@ actions:
If you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.
To learn more, check out [Spaces](https://www.elastic.co/guide/en/kibana/master/xpack-spaces.html).
To learn more, check out [Spaces](https://www.elastic.co/guide/en/kibana/8.x/xpack-spaces.html).
# Add some tag descriptions and displayNames
- target: '$.tags[?(@.name=="alerting")]'
description: Change tag description and displayName
@ -34,7 +34,7 @@ actions:
Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
externalDocs:
description: Alerting documentation
url: https://www.elastic.co/guide/en/kibana/master/alerting-getting-started.html
url: https://www.elastic.co/guide/en/kibana/8.x/alerting-getting-started.html
x-displayName: "Alerting"
- target: '$.tags[?(@.name=="cases")]'
description: Change tag description and displayName
@ -45,7 +45,7 @@ actions:
You can also send cases to external incident management systems by configuring connectors.
externalDocs:
description: Cases documentation
url: https://www.elastic.co/guide/en/kibana/master/cases.html
url: https://www.elastic.co/guide/en/kibana/8.x/cases.html
x-displayName: "Cases"
- target: '$.tags[?(@.name=="connectors")]'
description: Change tag description and displayName
@ -55,7 +55,7 @@ actions:
Alerting rules can use connectors to run actions when rule conditions are met.
externalDocs:
description: Connector documentation
url: https://www.elastic.co/guide/en/kibana/current/action-types.html
url: https://www.elastic.co/guide/en/kibana/8.x/action-types.html
x-displayName: "Connectors"
- target: '$.tags[?(@.name=="data views")]'
description: Change displayName
@ -72,7 +72,7 @@ actions:
description: Manage the roles that grant Elasticsearch and Kibana privileges.
externalDocs:
description: Kibana role management
url: https://www.elastic.co/guide/en/kibana/master/kibana-role-management.html
url: https://www.elastic.co/guide/en/kibana/8.x/kibana-role-management.html
- target: '$.tags[?(@.name=="slo")]'
description: Change displayName
update:
@ -83,7 +83,7 @@ actions:
x-displayName: "Spaces"
description: Manage your Kibana spaces.
externalDocs:
url: https://www.elastic.co/guide/en/kibana/master/xpack-spaces.html
url: https://www.elastic.co/guide/en/kibana/8.x/xpack-spaces.html
description: Space overview
- target: '$.tags[?(@.name=="system")]'
description: Change displayName and description
@ -164,4 +164,39 @@ actions:
application/json; Elastic-Api-Version=2023-10-31:
examples:
updateObjectSpacesResponseExample1:
$ref: "../examples/update_saved_objects_spaces_response1.yaml"
$ref: "../examples/update_saved_objects_spaces_response1.yaml"
- target: "$.paths['/api/security/role/{name}']['put']"
description: "Add examples to create role API"
update:
requestBody:
content:
application/json; Elastic-Api-Version=2023-10-31:
examples:
createRoleRequest1:
$ref: "../examples/create_role_request1.yaml"
createRoleRequest2:
$ref: "../examples/create_role_request2.yaml"
createRoleRequest3:
$ref: "../examples/create_role_request3.yaml"
createRoleRequest4:
$ref: "../examples/create_role_request4.yaml"
- target: "$.paths['/api/security/role/{name}']['get']"
description: "Add example to get role API"
update:
responses:
200:
content:
application/json; Elastic-Api-Version=2023-10-31:
examples:
getRoleResponse1:
$ref: '../examples/get_role_response1.yaml'
- target: "$.paths['/api/security/role']['get']"
description: "Add example to get roles API"
update:
responses:
200:
content:
application/json; Elastic-Api-Version=2023-10-31:
examples:
getRolesResponse1:
$ref: '../examples/get_roles_response1.yaml'

147
x-pack/packages/security/plugin_types_server/src/authorization/role_schema.ts
View file

@ -20,8 +20,16 @@ export const elasticsearchRoleSchema = schema.object({
* An optional list of cluster privileges. These privileges define the cluster level actions that
* users with this role are able to execute
*/
cluster: schema.maybe(schema.arrayOf(schema.string())),
cluster: schema.maybe(
schema.arrayOf(
schema.string({
meta: {
description:
'Cluster privileges that define the cluster level actions that users can perform.',
},
})
)
),
/**
* An optional list of remote cluster privileges. These privileges define the remote cluster level actions that
* users with this role are able to execute
@ -29,8 +37,24 @@ export const elasticsearchRoleSchema = schema.object({
remote_cluster: schema.maybe(
schema.arrayOf(
schema.object({
privileges: schema.arrayOf(schema.string(), { minSize: 1 }),
clusters: schema.arrayOf(schema.string(), { minSize: 1 }),
privileges: schema.arrayOf(
schema.string({
meta: {
description:
'The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.',
},
}),
{ minSize: 1 }
),
clusters: schema.arrayOf(
schema.string({
meta: {
description:
'A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.',
},
}),
{ minSize: 1 }
),
})
)
),
@ -45,7 +69,15 @@ export const elasticsearchRoleSchema = schema.object({
* Required list of indices (or index name patterns) to which the permissions in this
* entry apply.
*/
names: schema.arrayOf(schema.string(), { minSize: 1 }),
names: schema.arrayOf(
schema.string({
meta: {
description:
'The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).',
},
}),
{ minSize: 1 }
),
/**
* An optional set of the document fields that the owners of the role have read access to.
@ -53,7 +85,13 @@ export const elasticsearchRoleSchema = schema.object({
field_security: schema.maybe(
schema.recordOf(
schema.oneOf([schema.literal('grant'), schema.literal('except')]),
schema.arrayOf(schema.string())
schema.arrayOf(
schema.string({
meta: {
description: 'The document fields that the role members have read access to.',
},
})
)
)
),
@ -61,20 +99,42 @@ export const elasticsearchRoleSchema = schema.object({
* Required list of the index level privileges that the owners of the role have on the
* specified indices.
*/
privileges: schema.arrayOf(schema.string(), { minSize: 1 }),
privileges: schema.arrayOf(
schema.string({
meta: {
description:
'The index level privileges that the role members have for the data streams and indices.',
},
}),
{ minSize: 1 }
),
/**
* An optional search query that defines the documents the owners of the role have read access
* to. A document within the specified indices must match this query in order for it to be
* accessible by the owners of the role.
*/
query: schema.maybe(schema.string()),
query: schema.maybe(
schema.string({
meta: {
description:
'A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.',
},
})
),
/**
* An optional flag used to indicate if index pattern wildcards or regexps should cover
* restricted indices.
*/
allow_restricted_indices: schema.maybe(schema.boolean()),
allow_restricted_indices: schema.maybe(
schema.boolean({
meta: {
description:
'Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.',
},
})
),
})
)
),
@ -88,13 +148,29 @@ export const elasticsearchRoleSchema = schema.object({
/**
* Required list of remote clusters to which the permissions in this entry apply.
*/
clusters: schema.arrayOf(schema.string(), { minSize: 1 }),
clusters: schema.arrayOf(
schema.string({
meta: {
description:
'A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.',
},
}),
{ minSize: 1 }
),
/**
* Required list of remote indices (or index name patterns) to which the permissions in this
* entry apply.
*/
names: schema.arrayOf(schema.string(), { minSize: 1 }),
names: schema.arrayOf(
schema.string({
meta: {
description:
'A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).',
},
}),
{ minSize: 1 }
),
/**
* An optional set of the document fields that the owners of the role have read access to.
@ -102,7 +178,13 @@ export const elasticsearchRoleSchema = schema.object({
field_security: schema.maybe(
schema.recordOf(
schema.oneOf([schema.literal('grant'), schema.literal('except')]),
schema.arrayOf(schema.string())
schema.arrayOf(
schema.string({
meta: {
description: 'The document fields that the role members have read access to.',
},
})
)
)
),
@ -110,20 +192,42 @@ export const elasticsearchRoleSchema = schema.object({
* Required list of the index level privileges that the owners of the role have on the
* specified indices.
*/
privileges: schema.arrayOf(schema.string(), { minSize: 1 }),
privileges: schema.arrayOf(
schema.string({
meta: {
description:
'The index level privileges that role members have for the specified indices.',
},
}),
{ minSize: 1 }
),
/**
* An optional search query that defines the documents the owners of the role have read access
* to. A document within the specified indices must match this query in order for it to be
* accessible by the owners of the role.
*/
query: schema.maybe(schema.string()),
query: schema.maybe(
schema.string({
meta: {
description:
'A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members. ',
},
})
),
/**
* An optional flag used to indicate if index pattern wildcards or regexps should cover
* restricted indices.
*/
allow_restricted_indices: schema.maybe(schema.boolean()),
allow_restricted_indices: schema.maybe(
schema.boolean({
meta: {
description:
'Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.',
},
})
),
})
)
),
@ -131,7 +235,13 @@ export const elasticsearchRoleSchema = schema.object({
/**
* An optional list of users that the owners of this role can impersonate.
*/
run_as: schema.maybe(schema.arrayOf(schema.string())),
run_as: schema.maybe(
schema.arrayOf(
schema.string({
meta: { description: 'A user name that the role member can impersonate.' },
})
)
),
});
const allSpacesSchema = schema.arrayOf(schema.literal(GLOBAL_RESOURCE), {
@ -147,6 +257,7 @@ const spacesSchema = schema.oneOf(
allSpacesSchema,
schema.arrayOf(
schema.string({
meta: { description: 'A space that the privilege applies to.' },
validate(value) {
if (!/^[a-z0-9_-]+$/.test(value)) {
return `must be lower case, a-z, 0-9, '_', and '-' are allowed`;
@ -188,6 +299,7 @@ export const getKibanaRoleSchema = (
allSpacesSchema,
schema.arrayOf(
schema.string({
meta: { description: 'A base privilege that grants applies to all spaces.' },
validate(value) {
const globalPrivileges = getBasePrivilegeNames().global;
if (!globalPrivileges.some((privilege) => privilege === value)) {
@ -198,6 +310,7 @@ export const getKibanaRoleSchema = (
),
schema.arrayOf(
schema.string({
meta: { description: 'A base privilege that applies to specific spaces.' },
validate(value) {
const spacePrivileges = getBasePrivilegeNames().space;
if (!spacePrivileges.some((privilege) => privilege === value)) {
@ -218,6 +331,7 @@ export const getKibanaRoleSchema = (
feature: schema.maybe(
schema.recordOf(
schema.string({
meta: { description: 'The name of a feature.' },
validate(value) {
if (!FEATURE_NAME_VALUE_REGEX.test(value)) {
return `only a-z, A-Z, 0-9, '_', and '-' are allowed`;
@ -226,6 +340,7 @@ export const getKibanaRoleSchema = (
}),
schema.arrayOf(
schema.string({
meta: { description: 'The privileges that the role member has for the feature.' },
validate(value) {
if (!FEATURE_NAME_VALUE_REGEX.test(value)) {
return `only a-z, A-Z, 0-9, '_', and '-' are allowed`;

5
x-pack/plugins/security/server/routes/authorization/roles/delete.ts
View file

@ -29,6 +29,11 @@ export function defineDeleteRolesRoutes({ router }: RouteDefinitionParams) {
request: {
params: schema.object({ name: schema.string({ minLength: 1 }) }),
},
response: {
204: {
description: 'Indicates a successful call.',
},
},
},
},
createLicensedRouteHandler(async (context, request, response) => {

23
x-pack/plugins/security/server/routes/authorization/roles/get.ts
View file

@ -34,11 +34,30 @@ export function defineGetRolesRoutes({
version: API_VERSIONS.roles.public.v1,
validate: {
request: {
params: schema.object({ name: schema.string({ minLength: 1 }) }),
params: schema.object({
name: schema.string({
minLength: 1,
meta: { description: 'The role name.' },
}),
}),
query: schema.maybe(
schema.object({ replaceDeprecatedPrivileges: schema.maybe(schema.boolean()) })
schema.object({
replaceDeprecatedPrivileges: schema.maybe(
schema.boolean({
meta: {
description:
'If `true` and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.',
},
})
),
})
),
},
response: {
200: {
description: 'Indicates a successful call.',
},
},
},
},
createLicensedRouteHandler(async (context, request, response) => {

16
x-pack/plugins/security/server/routes/authorization/roles/get_all.ts
View file

@ -36,9 +36,23 @@ export function defineGetAllRolesRoutes({
validate: {
request: {
query: schema.maybe(
schema.object({ replaceDeprecatedPrivileges: schema.maybe(schema.boolean()) })
schema.object({
replaceDeprecatedPrivileges: schema.maybe(
schema.boolean({
meta: {
description:
'If `true` and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.',
},
})
),
})
),
},
response: {
200: {
description: 'Indicates a successful call.',
},
},
},
},
createLicensedRouteHandler(async (context, request, response) => {

19
x-pack/plugins/security/server/routes/authorization/roles/model/put_payload.ts
View file

@ -53,13 +53,28 @@ export function getPutPayloadSchema(
/**
* Optional text to describe the Role
*/
description: schema.maybe(schema.string({ maxLength: 2048 })),
description: schema.maybe(
schema.string({
maxLength: 2048,
meta: { description: 'A description for the role.' },
})
),
/**
* An optional meta-data dictionary. Within the metadata, keys that begin with _ are reserved
* for system usage.
*/
metadata: schema.maybe(schema.recordOf(schema.string(), schema.any())),
metadata: schema.maybe(
schema.recordOf(
schema.string({
meta: {
description:
'A metadata dictionary. Keys that begin with `_` are reserved for system usage.',
},
}),
schema.any()
)
),
/**
* Elasticsearch specific portion of the role definition.

5
x-pack/plugins/security/server/routes/authorization/roles/post.ts
View file

@ -62,6 +62,11 @@ export function defineBulkCreateOrUpdateRolesRoutes({
};
}),
},
response: {
200: {
description: 'Indicates a successful call.',
},
},
},
},
createLicensedRouteHandler(async (context, request, response) => {

22
x-pack/plugins/security/server/routes/authorization/roles/put.ts
View file

@ -26,6 +26,8 @@ export function definePutRolesRoutes({
path: '/api/security/role/{name}',
access: 'public',
summary: `Create or update a role`,
description:
'Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.',
options: {
tags: ['oas-tag:roles'],
},
@ -35,8 +37,19 @@ export function definePutRolesRoutes({
version: API_VERSIONS.roles.public.v1,
validate: {
request: {
params: schema.object({ name: schema.string({ minLength: 1, maxLength: 1024 }) }),
query: schema.object({ createOnly: schema.boolean({ defaultValue: false }) }),
params: schema.object({
name: schema.string({
minLength: 1,
maxLength: 1024,
meta: { description: 'The role name.' },
}),
}),
query: schema.object({
createOnly: schema.boolean({
defaultValue: false,
meta: { description: 'When true, a role is not overwritten if it already exists.' },
}),
}),
body: getPutPayloadSchema(() => {
const privileges = authz.privileges.get();
return {
@ -45,6 +58,11 @@ export function definePutRolesRoutes({
};
}),
},
response: {
204: {
description: 'Indicates a successful call.',
},
},
},
},
createLicensedRouteHandler(async (context, request, response) => {