diff --git a/docs/api/role-management.asciidoc b/docs/api/role-management.asciidoc index 7fbded3e57dd3..837e63bff74f0 100644 --- a/docs/api/role-management.asciidoc +++ b/docs/api/role-management.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[role-management-api]] == {kib} role management APIs @@ -6,19 +5,4 @@ Manage the roles that grant <>. 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: - -* <> to create a new {kib} role, or update the attributes of an existing role -* <> to create a new {kib} roles, or update the attributes of existing roles - -* <> to retrieve all {kib} roles - -* <> to retrieve a specific role - -* <> 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]. diff --git a/docs/api/role-management/delete.asciidoc b/docs/api/role-management/delete.asciidoc deleted file mode 100644 index 530e1e252ef8f..0000000000000 --- a/docs/api/role-management/delete.asciidoc +++ /dev/null @@ -1,26 +0,0 @@ -[[role-management-api-delete]] -=== Delete role API -++++ -Delete role -++++ - -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 :/api/security/role/my_admin_role` - -[[role-management-api-delete-response-codes]] -==== Response codes - -`204`:: - Indicates a successful call. - -`404`:: - Indicates an unsuccessful call. diff --git a/docs/api/role-management/get-all.asciidoc b/docs/api/role-management/get-all.asciidoc deleted file mode 100644 index 56c8b2c78859b..0000000000000 --- a/docs/api/role-management/get-all.asciidoc +++ /dev/null @@ -1,80 +0,0 @@ -[[role-management-api-get]] -=== Get all {kib} roles API -++++ -Get all roles -++++ - -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 :/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": [ ] - } -] --------------------------------------------------- diff --git a/docs/api/role-management/get.asciidoc b/docs/api/role-management/get.asciidoc deleted file mode 100644 index 95f944a56e150..0000000000000 --- a/docs/api/role-management/get.asciidoc +++ /dev/null @@ -1,106 +0,0 @@ -[[role-management-specific-api-get]] -=== Get specific role API -++++ -Get specific role -++++ - -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 :/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" - ] - } - ] -} --------------------------------------------------- diff --git a/docs/api/role-management/put-bulk.asciidoc b/docs/api/role-management/put-bulk.asciidoc deleted file mode 100644 index a11de47167e05..0000000000000 --- a/docs/api/role-management/put-bulk.asciidoc +++ /dev/null @@ -1,377 +0,0 @@ -[[role-management-api-put-bulk]] -=== Bulk create or update roles API -++++ -Bulk create or update roles API -++++ - -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 :/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. -`` (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 <> 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 <>. - -`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 diff --git a/docs/api/role-management/put.asciidoc b/docs/api/role-management/put.asciidoc deleted file mode 100644 index d68f3928a4063..0000000000000 --- a/docs/api/role-management/put.asciidoc +++ /dev/null @@ -1,238 +0,0 @@ -[[role-management-api-put]] -=== Create or update role API -++++ -Create or update role -++++ - -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 :/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 <> 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 <>. - -`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 diff --git a/docs/developer/architecture/security/rbac.asciidoc b/docs/developer/architecture/security/rbac.asciidoc index bf75ec1715de0..11896da243f2d 100644 --- a/docs/developer/architecture/security/rbac.asciidoc +++ b/docs/developer/architecture/security/rbac.asciidoc @@ -77,7 +77,7 @@ The application is created by concatenating the prefix of `kibana-` with the val } ---------------------------------- -Roles that grant <> should be managed using the <> 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 <> 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]] diff --git a/docs/management/watcher-ui/index.asciidoc b/docs/management/watcher-ui/index.asciidoc index 96ad0d3acc287..2e941cb86ca0b 100644 --- a/docs/management/watcher-ui/index.asciidoc +++ b/docs/management/watcher-ui/index.asciidoc @@ -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 -<>. 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. diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc index 1fa61881eca92..84cf809c66667 100644 --- a/docs/redirects.asciidoc +++ b/docs/redirects.asciidoc @@ -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]. \ No newline at end of file +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]. diff --git a/docs/setup/configuring-reporting.asciidoc b/docs/setup/configuring-reporting.asciidoc index a1b2f7e9af583..4213cf38b6398 100644 --- a/docs/setup/configuring-reporting.asciidoc +++ b/docs/setup/configuring-reporting.asciidoc @@ -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 <> 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 <> 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 <>. -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 :/api/security/role/custom_reporting_user diff --git a/docs/user/introduction.asciidoc b/docs/user/introduction.asciidoc index f3281b9bed175..48c9dfd91c9c6 100644 --- a/docs/user/introduction.asciidoc +++ b/docs/user/introduction.asciidoc @@ -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 <>. +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}] diff --git a/docs/user/security/api-keys/index.asciidoc b/docs/user/security/api-keys/index.asciidoc index 5b3dd206b5408..2f9a0d337e3b9 100644 --- a/docs/user/security/api-keys/index.asciidoc +++ b/docs/user/security/api-keys/index.asciidoc @@ -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 <>. +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]] diff --git a/docs/user/security/authorization/kibana-privileges.asciidoc b/docs/user/security/authorization/kibana-privileges.asciidoc index 581210bb9d393..6c9a94a354fb3 100644 --- a/docs/user/security/authorization/kibana-privileges.asciidoc +++ b/docs/user/security/authorization/kibana-privileges.asciidoc @@ -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 <>: +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 <>: +Using the {api-kibana}/group/endpoint-roles[role APIs]: [source,js] -------------------------------------------------- PUT /api/security/role/my_kibana_role diff --git a/docs/user/security/index.asciidoc b/docs/user/security/index.asciidoc index 906aee3d76d5a..44d7c41391c35 100644 --- a/docs/user/security/index.asciidoc +++ b/docs/user/security/index.asciidoc @@ -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 <>. For more information on configuring roles for {kib}, see <>. +the {api-kibana}/group/endpoint-roles[role APIs]. For more information on configuring roles for {kib}, see <>. 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[] diff --git a/oas_docs/bundle.json b/oas_docs/bundle.json index 6bca9024e77ea..d2550d7cca7f2 100644 --- a/oas_docs/bundle.json +++ b/oas_docs/bundle.json @@ -41354,6 +41354,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, @@ -41362,7 +41363,11 @@ } } ], - "responses": {}, + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, "summary": "Get all roles", "tags": [ "roles" @@ -41405,7 +41410,11 @@ } } ], - "responses": {}, + "responses": { + "204": { + "description": "Indicates a successful call." + } + }, "summary": "Delete a role", "tags": [ "roles" @@ -41427,6 +41436,7 @@ } }, { + "description": "The role name.", "in": "path", "name": "name", "required": true, @@ -41436,6 +41446,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, @@ -41444,13 +41455,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": [ { @@ -41476,6 +41492,7 @@ } }, { + "description": "The role name.", "in": "path", "name": "name", "required": true, @@ -41486,6 +41503,7 @@ } }, { + "description": "When true, a role is not overwritten if it already exists.", "in": "query", "name": "createOnly", "required": false, @@ -41502,6 +41520,7 @@ "additionalProperties": false, "properties": { "description": { + "description": "A description for the role.", "maxLength": 2048, "type": "string" }, @@ -41510,6 +41529,7 @@ "properties": { "cluster": { "items": { + "description": "Cluster privileges that define the cluster level actions that users can perform.", "type": "string" }, "type": "array" @@ -41519,11 +41539,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" @@ -41532,6 +41554,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, @@ -41539,12 +41562,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" } }, @@ -41562,6 +41587,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, @@ -41569,6 +41595,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, @@ -41588,10 +41615,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, @@ -41600,6 +41629,7 @@ "field_security": { "additionalProperties": { "items": { + "description": "The document fields that the role members have read access to.", "type": "string" }, "type": "array" @@ -41608,6 +41638,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, @@ -41615,12 +41646,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" } }, @@ -41635,6 +41668,7 @@ }, "run_as": { "items": { + "description": "A user name that the role member can impersonate.", "type": "string" }, "type": "array" @@ -41669,12 +41703,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" @@ -41684,6 +41720,7 @@ "feature": { "additionalProperties": { "items": { + "description": "The privileges that the role member has for the feature.", "type": "string" }, "type": "array" @@ -41705,6 +41742,7 @@ }, { "items": { + "description": "A space that the privilege applies to.", "type": "string" }, "type": "array" @@ -41735,7 +41773,11 @@ } } }, - "responses": {}, + "responses": { + "204": { + "description": "Indicates a successful call." + } + }, "summary": "Create or update a role", "tags": [ "roles" @@ -41780,6 +41822,7 @@ "additionalProperties": false, "properties": { "description": { + "description": "A description for the role.", "maxLength": 2048, "type": "string" }, @@ -41788,6 +41831,7 @@ "properties": { "cluster": { "items": { + "description": "Cluster privileges that define the cluster level actions that users can perform.", "type": "string" }, "type": "array" @@ -41797,11 +41841,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" @@ -41810,6 +41856,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, @@ -41817,12 +41864,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" } }, @@ -41840,6 +41889,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, @@ -41847,6 +41897,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, @@ -41866,10 +41917,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, @@ -41878,6 +41931,7 @@ "field_security": { "additionalProperties": { "items": { + "description": "The document fields that the role members have read access to.", "type": "string" }, "type": "array" @@ -41886,6 +41940,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, @@ -41893,12 +41948,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" } }, @@ -41913,6 +41970,7 @@ }, "run_as": { "items": { + "description": "A user name that the role member can impersonate.", "type": "string" }, "type": "array" @@ -41947,12 +42005,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" @@ -41962,6 +42022,7 @@ "feature": { "additionalProperties": { "items": { + "description": "The privileges that the role member has for the feature.", "type": "string" }, "type": "array" @@ -41983,6 +42044,7 @@ }, { "items": { + "description": "A space that the privilege applies to.", "type": "string" }, "type": "array" @@ -42021,7 +42083,11 @@ } } }, - "responses": {}, + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, "summary": "Create or update roles", "tags": [ "roles" diff --git a/oas_docs/bundle.serverless.json b/oas_docs/bundle.serverless.json index a8d428d5404fc..d415d769c175b 100644 --- a/oas_docs/bundle.serverless.json +++ b/oas_docs/bundle.serverless.json @@ -41354,6 +41354,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, @@ -41362,7 +41363,11 @@ } } ], - "responses": {}, + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, "summary": "Get all roles", "tags": [ "roles" @@ -41405,7 +41410,11 @@ } } ], - "responses": {}, + "responses": { + "204": { + "description": "Indicates a successful call." + } + }, "summary": "Delete a role", "tags": [ "roles" @@ -41427,6 +41436,7 @@ } }, { + "description": "The role name.", "in": "path", "name": "name", "required": true, @@ -41436,6 +41446,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, @@ -41444,13 +41455,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": [ { @@ -41476,6 +41492,7 @@ } }, { + "description": "The role name.", "in": "path", "name": "name", "required": true, @@ -41486,6 +41503,7 @@ } }, { + "description": "When true, a role is not overwritten if it already exists.", "in": "query", "name": "createOnly", "required": false, @@ -41502,6 +41520,7 @@ "additionalProperties": false, "properties": { "description": { + "description": "A description for the role.", "maxLength": 2048, "type": "string" }, @@ -41510,6 +41529,7 @@ "properties": { "cluster": { "items": { + "description": "Cluster privileges that define the cluster level actions that users can perform.", "type": "string" }, "type": "array" @@ -41519,11 +41539,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" @@ -41532,6 +41554,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, @@ -41539,12 +41562,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" } }, @@ -41562,6 +41587,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, @@ -41569,6 +41595,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, @@ -41588,10 +41615,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, @@ -41600,6 +41629,7 @@ "field_security": { "additionalProperties": { "items": { + "description": "The document fields that the role members have read access to.", "type": "string" }, "type": "array" @@ -41608,6 +41638,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, @@ -41615,12 +41646,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" } }, @@ -41635,6 +41668,7 @@ }, "run_as": { "items": { + "description": "A user name that the role member can impersonate.", "type": "string" }, "type": "array" @@ -41669,12 +41703,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" @@ -41684,6 +41720,7 @@ "feature": { "additionalProperties": { "items": { + "description": "The privileges that the role member has for the feature.", "type": "string" }, "type": "array" @@ -41705,6 +41742,7 @@ }, { "items": { + "description": "A space that the privilege applies to.", "type": "string" }, "type": "array" @@ -41735,7 +41773,11 @@ } } }, - "responses": {}, + "responses": { + "204": { + "description": "Indicates a successful call." + } + }, "summary": "Create or update a role", "tags": [ "roles" @@ -41780,6 +41822,7 @@ "additionalProperties": false, "properties": { "description": { + "description": "A description for the role.", "maxLength": 2048, "type": "string" }, @@ -41788,6 +41831,7 @@ "properties": { "cluster": { "items": { + "description": "Cluster privileges that define the cluster level actions that users can perform.", "type": "string" }, "type": "array" @@ -41797,11 +41841,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" @@ -41810,6 +41856,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, @@ -41817,12 +41864,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" } }, @@ -41840,6 +41889,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, @@ -41847,6 +41897,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, @@ -41866,10 +41917,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, @@ -41878,6 +41931,7 @@ "field_security": { "additionalProperties": { "items": { + "description": "The document fields that the role members have read access to.", "type": "string" }, "type": "array" @@ -41886,6 +41940,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, @@ -41893,12 +41948,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" } }, @@ -41913,6 +41970,7 @@ }, "run_as": { "items": { + "description": "A user name that the role member can impersonate.", "type": "string" }, "type": "array" @@ -41947,12 +42005,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" @@ -41962,6 +42022,7 @@ "feature": { "additionalProperties": { "items": { + "description": "The privileges that the role member has for the feature.", "type": "string" }, "type": "array" @@ -41983,6 +42044,7 @@ }, { "items": { + "description": "A space that the privilege applies to.", "type": "string" }, "type": "array" @@ -42021,7 +42083,11 @@ } } }, - "responses": {}, + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, "summary": "Create or update roles", "tags": [ "roles" diff --git a/oas_docs/examples/create_role_request1.yaml b/oas_docs/examples/create_role_request1.yaml new file mode 100644 index 0000000000000..1d041005f30de --- /dev/null +++ b/oas_docs/examples/create_role_request1.yaml @@ -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 diff --git a/oas_docs/examples/create_role_request2.yaml b/oas_docs/examples/create_role_request2.yaml new file mode 100644 index 0000000000000..d36d7e2330f3c --- /dev/null +++ b/oas_docs/examples/create_role_request2.yaml @@ -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 \ No newline at end of file diff --git a/oas_docs/examples/create_role_request3.yaml b/oas_docs/examples/create_role_request3.yaml new file mode 100644 index 0000000000000..55b4cb0834b9f --- /dev/null +++ b/oas_docs/examples/create_role_request3.yaml @@ -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 \ No newline at end of file diff --git a/oas_docs/examples/create_role_request4.yaml b/oas_docs/examples/create_role_request4.yaml new file mode 100644 index 0000000000000..f2332e2e934dc --- /dev/null +++ b/oas_docs/examples/create_role_request4.yaml @@ -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 \ No newline at end of file diff --git a/oas_docs/examples/get_role_response1.yaml b/oas_docs/examples/get_role_response1.yaml new file mode 100644 index 0000000000000..5e44481afa8ce --- /dev/null +++ b/oas_docs/examples/get_role_response1.yaml @@ -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: [] diff --git a/oas_docs/examples/get_roles_response1.yaml b/oas_docs/examples/get_roles_response1.yaml new file mode 100644 index 0000000000000..9c3a45163ace1 --- /dev/null +++ b/oas_docs/examples/get_roles_response1.yaml @@ -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: [] \ No newline at end of file diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index 05f614ede3df7..78c228171175b 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -36792,12 +36792,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 @@ -36826,7 +36832,9 @@ paths: schema: minLength: 1 type: string - responses: {} + responses: + '204': + description: Indicates a successful call. summary: Delete a role tags: - roles @@ -36841,22 +36849,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 @@ -36874,14 +36892,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: @@ -36895,6 +36915,7 @@ paths: type: object properties: description: + description: A description for the role. maxLength: 2048 type: string elasticsearch: @@ -36903,6 +36924,9 @@ paths: properties: cluster: items: + description: >- + Cluster privileges that define the cluster level + actions that users can perform. type: string type: array indices: @@ -36911,24 +36935,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 @@ -36941,11 +36996,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 @@ -36959,29 +37022,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 @@ -36990,6 +37088,7 @@ paths: type: array run_as: items: + description: A user name that the role member can impersonate. type: string type: array kibana: @@ -37008,14 +37107,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 @@ -37029,6 +37137,7 @@ paths: minItems: 1 type: array - items: + description: A space that the privilege applies to. type: string type: array default: @@ -37041,7 +37150,9 @@ paths: type: object required: - elasticsearch - responses: {} + responses: + '204': + description: Indicates a successful call. summary: Create or update a role tags: - roles @@ -37077,6 +37188,7 @@ paths: type: object properties: description: + description: A description for the role. maxLength: 2048 type: string elasticsearch: @@ -37085,6 +37197,9 @@ paths: properties: cluster: items: + description: >- + Cluster privileges that define the cluster level + actions that users can perform. type: string type: array indices: @@ -37093,24 +37208,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 @@ -37123,11 +37272,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 @@ -37141,29 +37298,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 @@ -37172,6 +37367,9 @@ paths: type: array run_as: items: + description: >- + A user name that the role member can + impersonate. type: string type: array kibana: @@ -37190,14 +37388,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 @@ -37211,6 +37418,7 @@ paths: minItems: 1 type: array - items: + description: A space that the privilege applies to. type: string type: array default: @@ -37226,7 +37434,9 @@ paths: type: object required: - roles - responses: {} + responses: + '200': + description: Indicates a successful call. summary: Create or update roles tags: - roles diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 044914ccc5758..e7d8b9240cf1f 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -40886,12 +40886,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 @@ -40920,7 +40926,9 @@ paths: schema: minLength: 1 type: string - responses: {} + responses: + '204': + description: Indicates a successful call. summary: Delete a role tags: - roles @@ -40935,22 +40943,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 @@ -40968,14 +40986,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: @@ -40989,6 +41009,7 @@ paths: type: object properties: description: + description: A description for the role. maxLength: 2048 type: string elasticsearch: @@ -40997,6 +41018,9 @@ paths: properties: cluster: items: + description: >- + Cluster privileges that define the cluster level + actions that users can perform. type: string type: array indices: @@ -41005,24 +41029,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 @@ -41035,11 +41090,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 @@ -41053,29 +41116,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 @@ -41084,6 +41182,7 @@ paths: type: array run_as: items: + description: A user name that the role member can impersonate. type: string type: array kibana: @@ -41102,14 +41201,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 @@ -41123,6 +41231,7 @@ paths: minItems: 1 type: array - items: + description: A space that the privilege applies to. type: string type: array default: @@ -41135,7 +41244,9 @@ paths: type: object required: - elasticsearch - responses: {} + responses: + '204': + description: Indicates a successful call. summary: Create or update a role tags: - roles @@ -41171,6 +41282,7 @@ paths: type: object properties: description: + description: A description for the role. maxLength: 2048 type: string elasticsearch: @@ -41179,6 +41291,9 @@ paths: properties: cluster: items: + description: >- + Cluster privileges that define the cluster level + actions that users can perform. type: string type: array indices: @@ -41187,24 +41302,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 @@ -41217,11 +41366,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 @@ -41235,29 +41392,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 @@ -41266,6 +41461,9 @@ paths: type: array run_as: items: + description: >- + A user name that the role member can + impersonate. type: string type: array kibana: @@ -41284,14 +41482,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 @@ -41305,6 +41512,7 @@ paths: minItems: 1 type: array - items: + description: A space that the privilege applies to. type: string type: array default: @@ -41320,7 +41528,9 @@ paths: type: object required: - roles - responses: {} + responses: + '200': + description: Indicates a successful call. summary: Create or update roles tags: - roles diff --git a/oas_docs/overlays/kibana.overlays.yaml b/oas_docs/overlays/kibana.overlays.yaml index 4a21c029ef80a..ed41f56088bf8 100644 --- a/oas_docs/overlays/kibana.overlays.yaml +++ b/oas_docs/overlays/kibana.overlays.yaml @@ -164,4 +164,39 @@ actions: application/json; Elastic-Api-Version=2023-10-31: examples: updateObjectSpacesResponseExample1: - $ref: "../examples/update_saved_objects_spaces_response1.yaml" \ No newline at end of file + $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' diff --git a/x-pack/packages/security/plugin_types_server/src/authorization/role_schema.ts b/x-pack/packages/security/plugin_types_server/src/authorization/role_schema.ts index 3d673fa25dc5f..6a10b3a4ee2ad 100644 --- a/x-pack/packages/security/plugin_types_server/src/authorization/role_schema.ts +++ b/x-pack/packages/security/plugin_types_server/src/authorization/role_schema.ts @@ -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`; diff --git a/x-pack/plugins/security/server/routes/authorization/roles/delete.ts b/x-pack/plugins/security/server/routes/authorization/roles/delete.ts index fe7c97b32d27b..07f314da4232b 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/delete.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/delete.ts @@ -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) => { diff --git a/x-pack/plugins/security/server/routes/authorization/roles/get.ts b/x-pack/plugins/security/server/routes/authorization/roles/get.ts index 760feb4d94950..031da53092b09 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/get.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/get.ts @@ -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) => { diff --git a/x-pack/plugins/security/server/routes/authorization/roles/get_all.ts b/x-pack/plugins/security/server/routes/authorization/roles/get_all.ts index 81164e0d38c59..5979922cd64e4 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/get_all.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/get_all.ts @@ -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) => { diff --git a/x-pack/plugins/security/server/routes/authorization/roles/model/put_payload.ts b/x-pack/plugins/security/server/routes/authorization/roles/model/put_payload.ts index 52c8178a651a7..4022098b9fd56 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/model/put_payload.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/model/put_payload.ts @@ -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. diff --git a/x-pack/plugins/security/server/routes/authorization/roles/post.ts b/x-pack/plugins/security/server/routes/authorization/roles/post.ts index 0fe918ee5cc3e..949553e960c9b 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/post.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/post.ts @@ -62,6 +62,11 @@ export function defineBulkCreateOrUpdateRolesRoutes({ }; }), }, + response: { + 200: { + description: 'Indicates a successful call.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/security/server/routes/authorization/roles/put.ts b/x-pack/plugins/security/server/routes/authorization/roles/put.ts index 16e2ab819e781..268c84ff7420e 100644 --- a/x-pack/plugins/security/server/routes/authorization/roles/put.ts +++ b/x-pack/plugins/security/server/routes/authorization/roles/put.ts @@ -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) => {