[DOC] Splits role mapping APIs into separate pages (#32797)

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

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

@@ -0,0 +1,74 @@
+[role="xpack"]
+[[security-api-get-role-mapping]]
+=== Get role mappings API
+
+Retrieves role mappings.
+
+==== Request
+
+`GET /_xpack/security/role_mapping` +
+
+`GET /_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. You can specify multiple 
+  mapping names as a comma-separated list. If you do not specify this
+  parameter, the API returns information about all role mappings. 
+
+//==== Request Body
+
+==== Results
+
+A successful call retrieves an object, where the keys are the
+names of the request mappings, and the values are the JSON representation of 
+those mappings. For more information, see 
+<<role-mapping-resources>>.
+
+If there is no mapping with the requested name, the
+response will have status code `404`.
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example retrieves information about the `mapping1` role mapping:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/role_mapping/mapping1
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:role_mapping]
+
+
+[source,js]
+--------------------------------------------------
+{
+  "mapping1": {
+    "enabled": true,
+    "roles": [
+      "user"
+    ],
+    "rules": {
+      "field": {
+        "username": "*"
+      }
+    },
+    "metadata": {}
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE

x-pack/docs/en/rest-api/security/role-mapping-resources.asciidoc

@@ -0,0 +1,89 @@
+[role="xpack"]
+[[role-mapping-resources]]
+=== Role mapping resources
+
+A role mapping resource has the following properties: 
+
+`enabled`::
+(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`::
+(list) A list of roles that are granted to the users that match the role mapping
+rules.
+
+`rules`::
+(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. The DSL supports the following rule types:
+`any`::: 
+(array of rules) If *any* of its children are true, it evaluates to `true`.
+`all`::: 
+(array of rules) If *all* of its children are true, it evaluates to `true`.
+`field`::: 
+(object) See <<mapping-roles-rule-field>>. 
+`except`::
+(object) A single rule as an object. Only valid as a child of an `all` rule. If 
+its child is `false`, the `except` is `true`.
+
+
+[float]
+[[mapping-roles-rule-field]]
+==== Field rules
+
+The `field` rule is the primary building block for a role mapping expression.
+It takes a single object as its value and that object must contain a single
+member with key _F_ and value _V_. The field rule looks up the value of _F_
+within the user object and then tests whether the user value _matches_ the
+provided value _V_.
+
+The value specified in the field rule can be one of the following types:
+[cols="2,5,3m"]
+|=======================
+| Type               | Description | Example
+
+| Simple String      | Exactly matches the provided value.                             | "esadmin"
+| Wildcard String    | Matches the provided value using a wildcard.                    | "*,dc=example,dc=com"
+| Regular Expression | Matches the provided value using a
+                       {ref}/query-dsl-regexp-query.html#regexp-syntax[Lucene regexp]. | "/.\*-admin[0-9]*/"
+| Number             | Matches an equivalent numerical value.                          | 7
+| Null               | Matches a null or missing value.                                | null
+| Array              | Tests each element in the array in
+                      accordance with the above definitions.
+                      If _any_ of elements match, the match is successful.             | ["admin", "operator"]
+|=======================
+
+[float]
+===== User fields
+
+The _user object_ against which rules are evaluated has the following fields:
+
+`username`::
+(string) The username by which {security} knows this user. For example, `"username": "jsmith"`.
+`dn`::
+(string) The _Distinguished Name_ of the user. For example, `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`.
+`groups`::
+(array of strings) The groups to which the user belongs. For example, `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com","cn=esusers,ou=groups,dc=example,dc=com ]`.
+`metadata`::
+(object) Additional metadata for the user. For example, `"metadata": { "cn": "John Smith" }`.
+`realm`::  
+(object) The realm that authenticated the user. The only field in this object is the realm name. For example, `"realm": { "name": "ldap1" }`.
+
+The `groups` field is multi-valued; a user can belong to many groups. When a
+`field` rule is applied against a multi-valued field, it is considered to match
+if _at least one_ of the member values matches. For example, the following rule
+matches any user who is a member of the `admin` group, regardless of any
+other groups they belong to:
+
+[source, js]
+------------------------------------------------------------
+{ "field" : { "groups" : "admin" } }
+------------------------------------------------------------
+// NOTCONSOLE
+
+For additional realm-specific details, see
+{stack-ov}/mapping-roles.html#ldap-role-mapping[Mapping Users and Groups to Roles].

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

@@ -1,404 +0,0 @@
-[role="xpack"]
-[[security-api-role-mapping]]
-=== Role Mapping APIs
-
-The Role Mapping API enables you to add, remove, and retrieve role mappings.
-
-==== Request
-
-`GET /_xpack/security/role_mapping` +
-
-`GET /_xpack/security/role_mapping/<name>` +
-
-`DELETE /_xpack/security/role_mapping/<name>` +
-
-`POST /_xpack/security/role_mapping/<name>` +
-
-`PUT /_xpack/security/role_mapping/<name>`
-
-==== Description
-
-Role mappings have _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-role-apis,role management APIs>> or
-{xpack-ref}/defining-roles.html#roles-management-file[roles files].
-
-The role mapping rule is a logical condition that is expressed using a JSON DSL.
-The DSL supports the following rule types:
-
-|=======================
-| Type     | Value Type (child)         | Description
-
-| `any`    | An array of rules          | If *any* of its children are true, it
-                                          evaluates to `true`.
-| `all`    | An array of rules          | If *all* of its children are true, it
-                                          evaluates to `true`.
-| `field`  | An object                  | See <<mapping-roles-rule-field>>
-| `except` | A single rule as an object | Only valid as a child of an `all`
-                                          rule. If its child is `false`, the
-                                          `except` is `true`.
-|=======================
-
-[float]
-[[mapping-roles-rule-field]]
-===== The Field Rule
-
-The `field` rule is the primary building block for a role-mapping expression.
-It takes a single object as its value and that object must contain a single
-member with key _F_ and value _V_. The field rule looks up the value of _F_
-within the user object and then tests whether the user value _matches_ the
-provided value _V_.
-
-The value specified in the field rule can be one of the following types:
-[cols="2,5,3m"]
-|=======================
-| Type               | Description | Example
-
-| Simple String      | Exactly matches the provided value.                             | "esadmin"
-| Wildcard String    | Matches the provided value using a wildcard.                    | "*,dc=example,dc=com"
-| Regular Expression | Matches the provided value using a
-                       {ref}/query-dsl-regexp-query.html#regexp-syntax[Lucene regexp]. | "/.\*-admin[0-9]*/"
-| Number             | Matches an equivalent numerical value.                          | 7
-| Null               | Matches a null or missing value.                                | null
-| Array              | Tests each element in the array in
-                      accordance with the above definitions.
-                      If _any_ of elements match, the match is successful.             | ["admin", "operator"]
-|=======================
-
-===== User Fields
-
-The _user object_ against which rules are evaluated has the following fields:
-[cols="1s,,,m"]
-|=======================
-| Name        | Type            | Description | Example
-
-| username    | string          | The username by which {security} knows this user. | `"username": "jsmith"`
-| dn          | string          | The _Distinguished Name_ of the user. | `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`
-| groups      | array-of-string | The groups to which the user belongs. | `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com",
-"cn=esusers,ou=groups,dc=example,dc=com ]`
-| metadata    | object          | Additional metadata for the user. | `"metadata": { "cn": "John Smith" }`
-| realm       | object          | The realm that authenticated the user. The only field in this object is the realm name. | `"realm": { "name": "ldap1" }`
-|=======================
-
-The `groups` field is multi-valued; a user can belong to many groups. When a
-`field` rule is applied against a multi-valued field, it is considered to match
-if _at least one_ of the member values matches. For example, the following rule
-matches any user who is a member of the `admin` group, regardless of any
-other groups they belong to:
-
-[source, js]
-------------------------------------------------------------
-{ "field" : { "groups" : "admin" } }
-------------------------------------------------------------
-// NOTCONSOLE
-
-For additional realm-specific details, see
-{xpack-ref}/mapping-roles.html#ldap-role-mapping[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. If you do not specify this
-  parameter for the Get Role Mappings API, it returns information about all
-  role mappings.
-
-
-==== 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.
-
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
-
-
-==== Examples
-
-[[security-api-put-role-mapping]]
-To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>` endpoint. 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
-
-[[security-api-get-role-mapping]]
-To retrieve a role mapping, issue a GET request to the
-`/_xpack/security/role_mapping/<name>` endpoint:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/role_mapping/mapping7
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-A successful call retrieves an object, where the keys are the
-names of the request mappings, and the values are
-the JSON representation of those mappings.
-If there is no mapping with the requested name, the
-response will have status code `404`.
-
-[source,js]
---------------------------------------------------
-{
-  "mapping7": {
-    "enabled": true,
-    "roles": [
-      "superuser"
-    ],
-    "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
-            }
-          }
-        }
-      ]
-    },
-    "metadata": {}
-  }
-}
---------------------------------------------------
-// TESTRESPONSE
-
-You can specify multiple mapping names as a comma-separated list.
-To retrieve all mappings, omit the name entirely.
-
-[[security-api-delete-role-mapping]]
-To delete a role mapping, submit a DELETE request to the
-`/_xpack/security/role_mapping/<name>` endpoint:
-
-[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

x-pack/docs/en/security/authentication/configuring-active-directory-realm.asciidoc

@@ -173,7 +173,7 @@ represent user roles for different systems in the organization.
 
 The `active_directory` realm enables you to map Active Directory users to roles
 via their Active Directory groups or other metadata. This role mapping can be
-configured via the <<security-api-role-mapping,role-mapping API>> or by using
+configured via the <<security-role-mapping-apis,role-mapping APIs>> or by using
 a file stored on each node. When a user authenticates against an Active
 Directory realm, the privileges for that user are the union of all privileges
 defined by the roles to which the user is mapped.

x-pack/docs/en/security/authentication/configuring-ldap-realm.asciidoc

@@ -133,7 +133,7 @@ supports both failover and load balancing modes of operation. See
 --
 The `ldap` realm enables you to map LDAP users to to roles via their LDAP
 groups, or other metadata. This role mapping can be configured via the
-{ref}/security-api-role-mapping.html[role-mapping API] or by using a file stored
+{ref}/security-api-put-role-mapping.html[add role mapping API] or by using a file stored
 on each node. When a user authenticates with LDAP, the privileges
 for that user are the union of all privileges defined by the roles to which
 the user is mapped.

x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc

@@ -126,7 +126,7 @@ The `certificate_authorities` option can be used as an alternative to the
 +
 --
 You map roles for PKI users through the 
-<<security-api-role-mapping,role-mapping API>> or by using a file stored on
+<<security-role-mapping-apis,role mapping APIs>> or by using a file stored on
 each node. When a user authenticates against a PKI realm, the privileges for
 that user are the union of all privileges defined by the roles to which the
 user is mapped.

x-pack/docs/en/security/authentication/saml-guide.asciidoc

@@ -592,9 +592,9 @@ When a user authenticates using SAML, they are identified to the Elastic Stack,
 but this does not automatically grant them access to perform any actions or
 access any data.
 
-Your SAML users cannot do anything until they are mapped to X-Pack Security
+Your SAML users cannot do anything until they are mapped to {security}
 roles. This mapping is performed through the
-{ref}/security-api-role-mapping.html[role-mapping API]
+{ref}/security-api-put-role-mapping.html[add role mapping API].
 
 This is an example of a simple role mapping that grants the `kibana_user` role
 to any user who authenticates against the `saml1` realm:
@@ -626,7 +626,7 @@ mapping are derived from the SAML attributes as follows:
 - `metadata`: See <<saml-user-metadata>>
 
 For more information, see <<mapping-roles>> and
-{ref}/security-api-role-mapping.html[Role Mapping APIs]. 
+{ref}/security-api.html#security-role-mapping-apis[role mapping APIs]. 
 
 If your IdP has the ability to provide groups or roles to Service Providers,
 then you should map this SAML attribute to the `attributes.groups` setting in

x-pack/docs/en/security/authorization/mapping-roles.asciidoc

@@ -28,7 +28,7 @@ you are able to map users to both API-managed roles and file-managed roles
 ==== Using the role mapping API
 
 You can define role-mappings through the
-{ref}/security-api-role-mapping.html[role mapping API].
+{ref}/security-api-put-role-mapping.html[add role mapping API].
 
 [[mapping-roles-file]]
 ==== Using role mapping files

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_role_mapping.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.delete_role_mapping": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-delete-role-mapping",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role-mapping.html",
     "methods": [ "DELETE" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_role_mapping.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.get_role_mapping": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-get-role-mapping",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role-mapping.html",
     "methods": [ "GET" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_role_mapping.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.put_role_mapping": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-put-role-mapping",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html",
     "methods": [ "PUT", "POST" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",