[DOC] Splits role mapping APIs into separate pages

docs/reference/redirects.asciidoc

@@ -531,3 +531,11 @@ native realm:
 * <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
 * <<security-api-change-password,Change passwords>>
 * <<security-api-get-user,Get users>>
+
+[role="exclude",id="security-api-role-mapping"]
+=== Role mapping APIs
+
+You can use the following APIs to add, remove, and retrieve role mappings:
+
+* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
+* <<security-api-get-role-mapping,Get role mappings>>

x-pack/docs/en/rest-api/defs.asciidoc

@@ -2,8 +2,8 @@
 [[ml-api-definitions]]
 == Definitions
 
-These resource definitions are used in {ml} APIs and in {kib} advanced
-job configuration options.
+These resource definitions are used in {ml} and {security} APIs and in {kib} 
+advanced {ml} job configuration options.
 
 * <<ml-calendar-resource,Calendars>>
 * <<ml-datafeed-resource,{dfeeds-cap}>>
@@ -13,6 +13,7 @@ job configuration options.
 * <<ml-jobstats,Job statistics>>
 * <<ml-snapshot-resource,Model snapshots>>
 * <<ml-results-resource,Results>>
+* <<role-mapping-resources,Role mappings>>
 * <<ml-event-resource,Scheduled Events>>
 
 [role="xpack"]
@@ -26,6 +27,8 @@ include::ml/jobresource.asciidoc[]
 [role="xpack"]
 include::ml/jobcounts.asciidoc[]
 [role="xpack"]
+include::security/role-mapping-resources.asciidoc[]
+[role="xpack"]
 include::ml/snapshotresource.asciidoc[]
 [role="xpack"]
 include::ml/resultsresource.asciidoc[]

x-pack/docs/en/rest-api/security.asciidoc

@@ -7,7 +7,6 @@ You can use the following APIs to perform {security} activities.
 * <<security-api-authenticate>>
 * <<security-api-clear-cache>>
 * <<security-api-privileges>>
-* <<security-api-role-mapping>>
 * <<security-api-ssl>>
 
 [float]
@@ -20,6 +19,15 @@ You can use the following APIs to add, remove, and retrieve roles in the native
 * <<security-api-clear-role-cache,Clear roles cache>>
 * <<security-api-get-role,Get roles>>
 
+[float]
+[[security-role-mapping-apis]]
+=== Role mappings
+
+You can use the following APIs to add, remove, and retrieve role mappings:
+
+* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
+* <<security-api-get-role-mapping,Get role mappings>>
+
 [float]
 [[security-token-apis]]
 === Tokens
@@ -44,17 +52,19 @@ native realm:
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
+include::security/create-role-mappings.asciidoc[]
 include::security/clear-roles-cache.asciidoc[]
 include::security/create-roles.asciidoc[]
 include::security/create-users.asciidoc[]
+include::security/delete-role-mappings.asciidoc[]
 include::security/delete-roles.asciidoc[]
 include::security/delete-tokens.asciidoc[]
 include::security/delete-users.asciidoc[]
 include::security/disable-users.asciidoc[]
 include::security/enable-users.asciidoc[]
+include::security/get-role-mappings.asciidoc[]
 include::security/get-roles.asciidoc[]
 include::security/get-tokens.asciidoc[]
 include::security/get-users.asciidoc[]
 include::security/privileges.asciidoc[]
-include::security/role-mapping.asciidoc[]
 include::security/ssl.asciidoc[]

x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc

@@ -0,0 +1,239 @@
+[role="xpack"]
+[[security-api-put-role-mapping]]
+=== Add role mappings API
+
+Adds and updates role mappings.
+
+==== Request
+
+`POST /_xpack/security/role_mapping/<name>` +
+
+`PUT /_xpack/security/role_mapping/<name>`
+
+
+==== Description
+
+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.  
+
+NOTE: This API does not create roles. Rather, it maps users to existing roles.
+Roles can be created by using <<security-api-roles, Role Management APIs>> or
+{stack-ov}/defining-roles.html#roles-management-file[roles files].
+
+For more information, see 
+{stack-ov}/mapping-roles.html[Mapping users and groups to roles].
+
+
+==== Path Parameters
+
+`name`::
+ (string) The distinct name that identifies the role mapping. The name is
+  used solely as an identifier to facilitate interaction via the API; it does
+  not affect the behavior of the mapping in any way.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT or POST request
+and pertain to adding a role mapping:
+
+`enabled` (required)::
+(boolean)  Mappings that have `enabled` set to `false` are ignored when role
+mapping is performed.
+
+`metadata`::
+(object) Additional metadata that helps define which roles are assigned to each
+user. Within the `metadata` object, keys beginning with `_` are reserved for
+system usage.
+
+`roles` (required)::
+(list) A list of roles that are granted to the users that match the role mapping
+rules.
+
+`rules` (required)::
+(object) The rules that determine which users should be matched by the mapping.
+A rule is a logical condition that is expressed by using a JSON DSL. See 
+<<role-mapping-resources>>. 
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example assigns the "user" role to all users:
+
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping1
+{
+  "roles": [ "user"],
+  "enabled": true, <1>
+  "rules": {
+    "field" : { "username" : "*" }
+  },
+  "metadata" : { <2>
+    "version" : 1
+  }
+}
+------------------------------------------------------------
+// CONSOLE
+<1> Mappings that have `enabled` set to `false` are ignored when role mapping
+    is performed.
+<2> Metadata is optional.
+
+A successful call returns a JSON structure that shows whether the mapping has
+been created or updated.
+
+[source,js]
+--------------------------------------------------
+{
+  "role_mapping" : {
+    "created" : true <1>
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+<1> When an existing mapping is updated, `created` is set to false.
+
+The following example assigns the "user" and "admin" roles to specific users:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/security/role_mapping/mapping2
+{
+  "roles": [ "user", "admin" ],
+  "enabled": true,
+  "rules": {
+     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+The following example matches any user where either the username is `esadmin`
+or the user is in the `cn=admin,dc=example,dc=com` group:
+
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping3
+{
+  "roles": [ "superuser" ],
+  "enabled": true,
+  "rules": {
+    "any": [
+      {
+        "field": {
+          "username": "esadmin"
+        }
+      },
+      {
+        "field": {
+          "groups": "cn=admins,dc=example,dc=com"
+        }
+      }
+    ]
+  }
+}
+------------------------------------------------------------
+// CONSOLE
+
+The following example matches users who authenticated against a specific realm:
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping4
+{
+  "roles": [ "ldap-user" ],
+  "enabled": true,
+  "rules": {
+    "field" : { "realm.name" : "ldap1" }
+  }
+}
+------------------------------------------------------------
+// CONSOLE
+
+The following example matches users within a specific LDAP sub-tree:
+
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping5
+{
+  "roles": [ "example-user" ],
+  "enabled": true,
+  "rules": {
+    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
+  }
+}
+------------------------------------------------------------
+// CONSOLE
+
+The following example matches users within a particular LDAP sub-tree in a
+specific realm:
+
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping6
+{
+  "roles": [ "ldap-example-user" ],
+  "enabled": true,
+  "rules": {
+    "all": [
+      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
+      { "field" : { "realm.name" : "ldap1" } }
+    ]
+  }
+}
+------------------------------------------------------------
+// CONSOLE
+
+The rules can be more complex and include wildcard matching. For example, the
+following mapping matches any user where *all* of these conditions are met:
+
+- the _Distinguished Name_ matches the pattern `*,ou=admin,dc=example,dc=com`,
+  or the username is `es-admin`, or the username is `es-system`
+- the user in in the `cn=people,dc=example,dc=com` group
+- the user does not have a `terminated_date`
+
+
+[source, js]
+------------------------------------------------------------
+POST /_xpack/security/role_mapping/mapping7
+{
+  "roles": [ "superuser" ],
+  "enabled": true,
+  "rules": {
+    "all": [
+      {
+        "any": [
+          {
+            "field": {
+              "dn": "*,ou=admin,dc=example,dc=com"
+            }
+          },
+          {
+            "field": {
+              "username": [ "es-admin", "es-system" ]
+            }
+          }
+        ]
+      },
+      {
+        "field": {
+          "groups": "cn=people,dc=example,dc=com"
+        }
+      },
+      {
+        "except": {
+          "field": {
+            "metadata.terminated_date": null
+          }
+        }
+      }
+    ]
+  }
+}
+------------------------------------------------------------
+// CONSOLE

x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc

@@ -0,0 +1,50 @@
+[role="xpack"]
+[[security-api-delete-role-mapping]]
+=== Delete role mappings API
+
+Removes role mappings.
+
+==== Request
+
+`DELETE /_xpack/security/role_mapping/<name>` 
+
+==== Description
+
+Role mappings define which roles are assigned to each user. For more information, 
+see {stack-ov}/mapping-roles.html[Mapping users and groups to roles]. 
+
+==== Path Parameters
+
+`name`::
+ (string) The distinct name that identifies the role mapping. The name is
+  used solely as an identifier to facilitate interaction via the API; it does
+  not affect the behavior of the mapping in any way.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example delete a role mapping:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/role_mapping/mapping1
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:role_mapping]
+
+If the mapping is successfully deleted, the request returns `{"found": true}`.
+Otherwise, `found` is set to false.
+
+[source,js]
+--------------------------------------------------
+{
+  "found" : true
+}
+--------------------------------------------------
+// TESTRESPONSE