From f785c31531acd2661c4df2c47b60b3e7fa16bf4b Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Wed, 25 Sep 2019 13:52:05 +0300 Subject: [PATCH] File based role definition documentation additions (#46304) (#47085) This commit clarifies and points out that the Role management UI and the Role management API cannot be used to manage roles that are defined in roles.yml and that file based role management is intended to have a small administrative scope and not handle all possible RBAC use cases. --- .../docs/en/rest-api/security/create-roles.asciidoc | 7 +++---- .../docs/en/rest-api/security/delete-roles.asciidoc | 6 ++---- x-pack/docs/en/rest-api/security/get-roles.asciidoc | 5 +++-- .../en/security/authorization/managing-roles.asciidoc | 11 ++++++++++- 4 files changed, 18 insertions(+), 11 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/create-roles.asciidoc b/x-pack/docs/en/rest-api/security/create-roles.asciidoc index 7eda4c22b0d..19802234f32 100644 --- a/x-pack/docs/en/rest-api/security/create-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-roles.asciidoc @@ -24,10 +24,9 @@ privilege. [[security-api-put-role-desc]] ==== {api-description-title} -The role API is generally the preferred way to manage roles, rather than using -file-based role management. For more information about the native realm, see -{stack-ov}/realms.html[Realms] and <>. - +The role management APIs are generally the preferred way to manage roles, rather than using +{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The create +or update roles API cannot update roles that are defined in roles files. [[security-api-put-role-path-params]] ==== {api-path-parms-title} diff --git a/x-pack/docs/en/rest-api/security/delete-roles.asciidoc b/x-pack/docs/en/rest-api/security/delete-roles.asciidoc index dec674b6577..ce5906ad8e3 100644 --- a/x-pack/docs/en/rest-api/security/delete-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-roles.asciidoc @@ -22,10 +22,8 @@ Removes roles in the native realm. [[security-api-delete-role-desc]] ==== {api-description-title} -The Roles API is generally the preferred way to manage roles, rather than using -file-based role management. For more information about the native realm, see -{stack-ov}/realms.html[Realms] and <>. - +The role management APIs are generally the preferred way to manage roles, rather than using +{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The delete roles API cannot remove roles that are defined in roles files. [[security-api-delete-role-path-params]] ==== {api-path-parms-title} diff --git a/x-pack/docs/en/rest-api/security/get-roles.asciidoc b/x-pack/docs/en/rest-api/security/get-roles.asciidoc index f014166362e..de7234697d3 100644 --- a/x-pack/docs/en/rest-api/security/get-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-roles.asciidoc @@ -23,8 +23,9 @@ privilege. [[security-api-get-role-desc]] ==== {api-description-title} -For more information about the native realm, see -{stack-ov}/realms.html[Realms] and <>. +The role management APIs are generally the preferred way to manage roles, rather than using +{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The get roles +API cannot retrieve roles that are defined in roles files. [[security-api-get-role-path-params]] ==== {api-path-parms-title} diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index ee984296f08..eab8e7f573b 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/managing-roles.asciidoc @@ -214,7 +214,16 @@ _Role Management APIs_, the role found in the file will be used. While the _Role Management APIs_ is the preferred mechanism to define roles, using the `roles.yml` file becomes useful if you want to define fixed roles that no one (beside an administrator having physical access to the {es} nodes) -would be able to change. +would be able to change. Please note however, that the `roles.yml` file is provided as a +minimal administrative function and is not intended to cover and be used +to define roles for all use cases. + +[IMPORTANT] +============================== +You cannot view, edit, or remove any roles that are defined in `roles.yml` by +using the <> or the +<>. +============================== [IMPORTANT] ==============================