From 2b1372adfd86998512669304e35fdf7ad76e9351 Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Mon, 14 Oct 2019 17:55:46 +0300 Subject: [PATCH] File based role mappings vs the role mapping APIs (#47015) (#47978) Make clear in the docs that the role mapping APIs is the preferred way to manage role mappings and that the role mappings that are defined in files cannot be viewed or managed with the APIs --- .../security/create-role-mappings.asciidoc | 8 ++++++-- .../security/delete-role-mappings.asciidoc | 7 ++++++- .../security/get-role-mappings.asciidoc | 7 ++++++- .../authorization/mapping-roles.asciidoc | 18 ++++++++++++++++++ 4 files changed, 36 insertions(+), 4 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc index 735e1d474e0..c325406c8ee 100644 --- a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc @@ -24,8 +24,12 @@ Creates and updates role mappings. ==== {api-description-title} Role mappings define which roles are assigned to each user. Each mapping has -_rules_ that identify users and a list of _roles_ that are -granted to those users. +_rules_ that identify users and a list of _roles_ that are granted to those users. + +The role mapping APIs are generally the preferred way to manage role mappings +rather than using {stack-ov}/mapping-roles.html#mapping-roles-file[role mapping files]. +The create or update role mappings API cannot update role mappings that are defined +in role mapping files. NOTE: This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using <> or diff --git a/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc index 489aa944805..c5dd1aa9c90 100644 --- a/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc @@ -21,7 +21,12 @@ Removes role mappings. ==== {api-description-title} Role mappings define which roles are assigned to each user. For more information, -see <>. +see <>. + +The role mapping APIs are generally the preferred way to manage role mappings +rather than using <>. +The delete role mappings API cannot remove role mappings that are defined +in role mapping files. [[security-api-delete-role-mapping-path-params]] ==== {api-path-parms-title} diff --git a/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc index 5243d775250..6fa79fe8a03 100644 --- a/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc @@ -23,7 +23,12 @@ Retrieves role mappings. ==== {api-description-title} Role mappings define which roles are assigned to each user. For more information, -see <>. +see <>. + +The role mapping APIs are generally the preferred way to manage role mappings +rather than using <>. +The get role mappings API cannot retrieve role mappings that are defined +in role mapping files. [[security-api-get-role-mapping-path-params]] ==== {api-path-parms-title} diff --git a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc b/x-pack/docs/en/security/authorization/mapping-roles.asciidoc index c202508caa3..012c8fc4ed9 100644 --- a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/mapping-roles.asciidoc @@ -66,6 +66,24 @@ You can change this default behavior by changing the this is a common setting in Elasticsearch, changing its value might effect other schedules in the system. +While the _role mapping APIs_ is he preferred way to manage role mappings, using +the `role_mappings.yml` file becomes useful in a couple of use cases: + +. If you want to define fixed role mappings that no one (besides an administrator +with physical access to the {es} nodes) would be able to change. + +. If cluster administration depends on users from external realms and these users +need to have their roles mapped to them even when the cluster is RED. For instance +an administrator that authenticates via LDAP or PKI and gets assigned an +administrator role so that they can perform corrective actions. + +Please note however, that the role_mappings.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 the role +mapping files by using the the role mapping APIs. + ==== Realm specific details [float] [[ldap-role-mapping]]