[DOCS] [Security] Documentation for Role Mapping API (elastic/x-pack-elasticsearch#1474)

Includes:
- Extensive changes to "mapping roles" section
- New section for role mapping API
- Updates to LDAP/AD/PKI realms to refer to API based role mapping 
- Updates to LDAP/AD realms: `unmapped_groups_as_roles` only looks at file-based mappings 
- Updates to LDAP/AD realms: new setting for "metadata"

Original commit: elastic/x-pack-elasticsearch@6349f665f5

docs/en/rest-api/security.asciidoc

@@ -5,6 +5,7 @@
 * <<security-api-clear-cache>>
 * <<security-api-users>>
 * <<security-api-roles>>
+* <<security-api-role-mapping>>
 * <<security-api-privileges>>
 * <<security-api-tokens>>
 
@@ -13,5 +14,6 @@ include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
 include::security/users.asciidoc[]
 include::security/roles.asciidoc[]
+include::security/role-mapping.asciidoc[]
 include::security/privileges.asciidoc[]
 include::security/tokens.asciidoc[]

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

@@ -0,0 +1,128 @@
+[[security-api-role-mapping]]
+=== Role Mapping APIs
+
+The Role Mapping API enables you to add, remove, and retrieve role-mappings.
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+NOTE: The API requires that each role-mapping have a distinct name. The name is
+ used solely as an identifier to facilitate interaction via the API, and does
+ not affect the behaviour of the mapping in any way.
+
+[[security-api-put-role-mapping]]
+To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
+endpoint:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/security/role_mapping/administrators
+{
+  "roles": [ "user", "admin" ],
+  "enabled": true, <1>
+  "rules": {
+     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
+  },
+  "metadata" : { <2>
+    "version" : 1
+  }
+}
+--------------------------------------------------
+// CONSOLE
+<1> Mappings that have `enabled` set to `false` will be ignored when role-mapping
+    is performed.
+<2> Metadata is optional
+
+The `roles`, `enabled`, and `rules` fields are required at the top-level.
+Within the `metadata` object, keys beginning with `_` are reserved for system
+usage.
+
+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.
+
+[[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/administrators
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+A successful call 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]
+--------------------------------------------------
+{
+  "administrators" : {
+    "enabled" : true,
+    "roles" : [
+      "user",
+      "admin"
+    ],
+    "rules" : {
+      "field" : {
+        "username" : [
+          "esadmin01",
+          "esadmin02"
+        ]
+      }
+    },
+    "metadata" : {
+      "version" : 1
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+You can specify multiple mapping names as a comma-separated list.
+To retrieve all mappings, omit the name entirely.
+
+[source,js]
+--------------------------------------------------
+# Retrieve mappings "m1", "m2", and "administrators"
+GET /_xpack/security/role_mapping/m1,m2,administrators
+
+# Retrieve all mappings
+GET /_xpack/security/role_mapping
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+[[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/administrators
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+If the mapping is successfully deleted, the request returns `{"found": true}`.
+Otherwise, `found` is set to false.
+
+[source,js]
+--------------------------------------------------
+{
+  "found" : true
+}
+--------------------------------------------------
+// TESTRESPONSE

docs/en/security/authentication/active-directory-realm.asciidoc

@@ -219,9 +219,12 @@ operation are supported: failover and load balancing
                                           `base_dn` is a group object and that it is the only group considered.
 | `unmapped_groups_as_roles` | no       | Specifies whether the names of any unmapped Active Directory
                                           groups should be used as role names and assigned to the user.
+                                          A group is considered to be _unmapped_ if it is not referenced
+                                          in any <<mapping-roles-file, role-mapping files>> (API based
+                                          role-mappings are not considered).
                                           Defaults to `false`.
 | `files.role_mapping`       | no       | Specifies the path and file name of the
-                                          <<ad-role-mapping, YAML role  mapping configuration file>>.
+                                          <<ldap-role-mapping, YAML role  mapping configuration file>>.
                                           Defaults to `CONF_DIR/x-pack/role_mapping.yml`,
                                           where `CONF_DIR` is `ES_HOME/config` (zip/tar installations)
                                           or `/etc/elasticsearch` (package installations).
@@ -229,6 +232,8 @@ operation are supported: failover and load balancing
                                           by the Active Directory server. Referrals are URLs returned by
                                           the server that are to be used to continue the LDAP operation
                                           (such as `search`). Defaults to `true`.
+| `metadata`                 | no       | Specifies the list of additional LDAP attributes that should
+                                          be stored in the `metadata` of an authenticated user.
 | `ssl.key`                  | no       | Specifies the path to the PEM encoded private key to use if the Active Directory
                                           server requires client authentication. `ssl.key` and `ssl.keystore.path` may not be used at the
                                           same time.
@@ -281,13 +286,55 @@ Active Directory server, the expectation is that their roles are managed there
 as well. In fact, Active Directory supports the notion of groups, which often
 represent user roles for different systems in the organization.
 
-The `active_directory` realm enables you to map Active Directory users and groups
+The `active_directory` realm enables you to map Active Directory users to roles
-to roles in the role mapping file stored on each node. You specify users and
+via their Active Directory groups, or other metadata. This role mapping can be
-groups using their distinguished names (DNs). For example, the following mapping
+configured via the <<security-api-role-mapping, role-mapping API>>, or by using
-configuration maps the Active Directory `admins` group to both the `monitoring`
+a file stored on each node. When a user authenticates against an Active
-and `user` roles, maps the `users` group to the `user` role and maps the `John Doe`
+Directory realm, the privileges for that user are the union of all privileges
-user to the `user` role.
+defined by the roles to which the user is mapped.
 
+Within a mapping definition, you specify groups using their distinguished
+names. For example, the following mapping configuration maps the Active
+Directory `admins` group to both the `monitoring` and `user` roles, maps the
+`users` group to the `user` role and maps the `John Doe` user to the `user`
+role.
+
+Configured via the role-mapping API:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/admins
+{
+  "roles" : [ "monitoring" , "user" ],
+  "rules" : { "field" : {
+    "groups" : "cn=admins,dc=example,dc=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The Active Directory distinguished name (DN) of the `admins` group.
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/basic_users
+{
+  "roles" : [ "user" ],
+  "rules" : { "any": [
+    { "field" : {
+      "groups" : "cn=users,dc=example,dc=com" <1>
+    } },
+    { "field" : {
+      "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" <2>
+    } }
+  ] },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The Active Directory distinguished name (DN) of the `users` group.
+<2> The Active Directory distinguished name (DN) of the user `John Doe`.
+
+Or, alternatively, configured via the role-mapping file:
 [source, yaml]
 ------------------------------------------------------------
 monitoring: <1>
@@ -307,7 +354,7 @@ For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
 [[ad-user-metadata]]
 ==== User Metadata in Active Directory Realms
 When a user is authenticated via an Active Directory realm, the following
-properties are populated in user's _metadata_. This metadata is returned in the
+properties are populated in the user's _metadata_. This metadata is returned in the
 <<security-api-authenticate,authenticate API>>, and can be used with
 <<templating-role-query, templated queries>> in roles.
 
@@ -319,6 +366,8 @@ properties are populated in user's _metadata_. This metadata is returned in the
                         groups were mapped to a role).
 |=======================
 
+Additional metadata can be extracted from the Active Directory server by configuring
+the `metadata` setting on the Active Directory realm.
 
 [[active-directory-ssl]]
 ==== Setting up SSL Between Elasticsearch and Active Directory

docs/en/security/authentication/ldap-realm.asciidoc

@@ -207,6 +207,9 @@ failover and load balancing modes of operation.
                                               the user DN is passed to the filter.
 | `unmapped_groups_as_roles`     | no       | Specifies whether the names of any unmapped LDAP groups
                                               should be used as role names and assigned to the user.
+                                              A group is considered to be _unmapped_ if it is not referenced
+                                              in any <<mapping-roles-file, role-mapping files>> (API based
+                                              role-mappings are not considered).
                                               Defaults to `false`.
 | `timeout.tcp_connect`          | no       | Specifies the TCP connect timeout period for establishing an
                                               LDAP connection. An `s` at the end indicates seconds, or `ms`
@@ -224,6 +227,8 @@ failover and load balancing modes of operation.
                                               returned by the LDAP server. Referrals are URLs returned by
                                               the server that are to be used to continue the LDAP operation
                                               (e.g. search). Defaults to `true`.
+| `metadata`                     | no       | Specifies the list of additional LDAP attributes that should
+                                              be stored in the `metadata` of an authenticated user.
 | `ssl.key`                      | no       | Specifies the path to the PEM encoded private key to use if the LDAP
                                               server requires client authentication. `ssl.key` and `ssl.keystore.path`
                                               may not be used at the same time.
@@ -330,15 +335,48 @@ the expectation is that their roles are managed there as well. If fact, LDAP
 supports the notion of groups, which often represent user roles for different
 systems in the organization.
 
-The `ldap` realm enables you to map LDAP groups to roles in the role mapping
+The `ldap` realm enables you to map LDAP users to to roles via their LDAP
-file stored on each node. When a user authenticates with LDAP, the privileges
+groups, or other metadata. This role mapping can be configured via the
-for that user are the union of all privileges defined by the roles assigned to
+<<security-api-role-mapping, role-mapping API>>, or by using a file stored
-the set of groups that the user belongs to.
+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.
 
-You specify groups using their distinguished names. For example, the following
+Within a mapping definition, you specify groups using their distinguished
-mapping configuration maps the LDAP `admins` group to both the `monitoring` and
+names. For example, the following mapping configuration maps the LDAP
-`user` roles, and maps the `users` group to the `user` role.
+`admins` group to both the `monitoring` and `user` roles, and maps the
+`users` group to the `user` role.
 
+Configured via the role-mapping API:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/admins
+{
+  "roles" : [ "monitoring" , "user" ],
+  "rules" : { "field" : {
+    "groups" : "cn=admins,dc=example,dc=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The LDAP distinguished name (DN) of the `admins` group.
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/basic_users
+{
+  "roles" : [ "user" ],
+  "rules" : { "field" : {
+    "groups" : "cn=users,dc=example,dc=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The LDAP distinguished name (DN) of the `users` group.
+
+Or, alternatively, configured via the role-mapping file:
 [source, yaml]
 ------------------------------------------------------------
 monitoring: <1>
@@ -368,6 +406,24 @@ populated in user's _metadata_. This metadata is returned in the
                         groups were mapped to a role).
 |=======================
 
+Additional fields can be included in the user's metadata by  configuring
+the `metadata` setting on the LDAP realm. This metadata is available for use
+with the <<mapping-roles-api, role mapping API>> or in
+<<templating-role-query, templated role queries>>.
+
+The example below includes the user's common name (`cn`) as an additional
+field in their metadata.
+[source,yaml]
+--------------------------------------------------
+xpack:
+  security:
+    authc:
+      realms:
+        ldap1:
+          type: ldap
+          metadata: cn
+--------------------------------------------------
+
 [[ldap-ssl]]
 ==== Setting up SSL Between Elasticsearch and LDAP
 

docs/en/security/authentication/pki-realm.asciidoc

@@ -117,10 +117,32 @@ xpack:
 [[assigning-roles-pki]]
 ==== Mapping Roles for PKI Users
 
-You map roles for PKI users in the role mapping file stored on each node. You
+You map roles for PKI users through the
-identify a user by the distinguished name in their certificate. For example, the
+<<security-api-role-mapping, role-mapping API>>, or by using a file stored on
-following mapping configuration maps `John Doe` to the `user` role:
+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.
 
+You identify a user by the distinguished name in their certificate.
+For example, the following mapping configuration maps `John Doe` to the
+`user` role:
+
+Using the role-mapping API:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/users
+{
+  "roles" : [ "user" ],
+  "rules" : { "field" : {
+    "dn" : "cn=John Doe,ou=example,o=com" <1>
+  } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+<1> The distinguished name (DN) of a PKI user.
+
+Or, alternatively, configured in a role-mapping file:
 [source, yaml]
 ------------------------------------------------------------
 user: <1>

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

@@ -5,7 +5,239 @@ If you authenticate users with the `native` or `file` realms, you can manage
 role assignment user the <<managing-native-users, User Management APIs>> or the
 <<managing-file-users, file-realm>> command-line tool respectively.
 
-For other types of realms, you configure role mappings for users and groups in a
+For other types of realms, you must create _role-mappings_ that define which
+roles should be assigned to each user based on their username, groups, or
+other metadata.
+
+{security} allows role-mappings to be defined via an
+<<mapping-roles-api, API>>, or managed through <<mapping-roles-file, files>>.
+These two sources of role-mapping are combined inside of {security}, so it is
+possible for a single user to have some roles that have been mapped through
+the API, and other roles that are mapped through files.
+
+When you use role-mappings, you assign existing roles to users.
+The available roles should either be added using the
+<<roles-management-api, Role Management APIs>> or defined in the
+<<roles-management-file, roles file>>. Either role-mapping method can use
+either role management method. For example, when you use the role mapping API,
+you are able to map users to both API-managed roles and file-managed roles
+(and likewise for file-based role-mappings).
+
+[[mapping-roles-api]]
+==== Using the Role Mapping API
+
+You can define role-mappings through the
+<<security-api-role-mapping, role mapping API>>.
+
+Each role-mapping has a distinct name which is used to interact with it via the
+API. The name does not affect the behaviour of the mapping in any way, but it
+is needed so that you can update or delete an existing mapping.
+
+A mapping has _rules_ that determine which users should be matched by this
+mapping, a list of _roles_ that will be granted to the users that match.
+
+The rule is a logical condition that is expressed using a JSON DSL.
+An mapping example with a simple rule is shown below:
+
+[source, js]
+------------------------------------------------------------
+{
+  "roles": [ "superuser" ],
+  "enabled": true,
+  "rules": {
+    "any": [
+      {
+        "field": {
+          "username": "esadmin"
+        }
+      },
+      {
+        "field": {
+          "groups": "cn=admins,dc=example,dc=com"
+        }
+      }
+    ]
+  }
+}
+------------------------------------------------------------
+// NOTCONSOLE
+
+This mapping matches any user where either of these conditions are met:
+
+- the username is `esadmin`
+- the user is in the `cn=admins,dc=example,dc=com` group
+
+
+The rules can be more complex and include wildcard matching:
+[source, js]
+------------------------------------------------------------
+{
+  "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
+          }
+        }
+      }
+    ]
+  }
+}
+------------------------------------------------------------
+// NOTCONSOLE
+
+The mapping above 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`
+
+[float]
+===== The Role Mapping DSL
+The DSL supports the following rule types:
+
+|=======================
+| Type     | Value Type (child)         | Description
+
+| `any`    | An array of rules          | Evaluates to `true` if *any* of its
+                                          children are true
+| `all`    | An array of rules          | Evaluates to `true` if *all* of its
+                                          children are true
+| `field`  | An object                  | <<mapping-roles-rule-field, See below>>
+| `except` | A single rule as an object | Only valid as a child of an `all`
+                                          rule, the `except` is `true` if its
+                                          child is `false` (negation).
+|=======================
+
+[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 value, and that object must contains 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 may be one of the following types:
+[cols="2,3m,5"]
+|=======================
+| Type               | Example                     | Description
+
+| Simple String      | "esadmin"                   | Matches exactly the provided value
+| Wildcard String    | "*,dc=example,dc=com"       | Matches the provided value using a wildcard
+| Regular Expression | "/.\*-admin[0-9]*/"         | Matches the provided value using a
+                                                     {ref}/query-dsl-regexp-query.html#regexp-syntax[Lucene regexp]
+| Number             | 7                           | Matches an equivalent numerical value
+| Null               | null                        | Matches a null, or missing value
+| Array              | ["admin", "operator"]       | Tests each element in the  array in
+                                                     accordance with the definitions above.
+                                                     The match is successful if _any_ of elements match.
+|=======================
+
+===== Available User Fields
+
+The _user object_ against which the rules are evaluated has the following fields:
+[cols="1s,1,3"]
+|=======================
+| Name        | Type            | Description
+
+| username    | string          | The username by which {security} knows this user.
+| dn          | string          | The _Distinguished Name_ of the user.
+| groups      | array-of-string | The groups to which the user belongs.
+| metadata    | object          | Additional metadata for the user.
+| realm       | object          | The realm that authenticated the user.
+                                  The only field in this object is the realm name.
+|=======================
+
+Example:
+[source, js]
+------------------------------------------------------------
+{
+  "username": "jsmith",
+  "dn"      : "cn=jsmith,ou=users,dc=example,dc=com",
+  "groups"  : [ "cn=admin,ou=groups,dc=example,dc=com", "cn=esusers,ou=groups,dc=example,dc=com" ],
+  "metadata": { "cn": "John Smith" },
+  "realm"   : { "name": "ldap1" }
+}
+------------------------------------------------------------
+// NOTCONSOLE
+
+The `groups` field is multi-valued - a user may 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. This means that the rule:
+
+[source, js]
+------------------------------------------------------------
+{ "field" : { "groups" : "admin" } }
+------------------------------------------------------------
+// NOTCONSOLE
+
+will match any user who is a member of the `admin` group, regardless of any
+other groups they may belong to.
+
+===== Role Mapping Examples
+
+- Match *all users*
+[source, js]
+------------------------------------------------------------
+{ "field" : { "username" : "*" } }
+------------------------------------------------------------
+// NOTCONSOLE
+
+- Match users who authenticated against a *specific realm*:
+[source, js]
+------------------------------------------------------------
+{ "field" : { "realm.name" : "ldap1" } }
+------------------------------------------------------------
+// NOTCONSOLE
+
+- Match users within a particular *LDAP sub-tree*: +
+[source, js]
+------------------------------------------------------------
+{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } }
+------------------------------------------------------------
+// NOTCONSOLE
+
+- Match users within a particular *LDAP sub-tree* in a *specific realm*:
+[source, js]
+------------------------------------------------------------
+{
+  "all": [
+    { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
+    { "field" : { "realm.name" : "ldap1" } }
+  ]
+}
+------------------------------------------------------------
+// NOTCONSOLE
+
+[[mapping-roles-file]]
+==== Using Role Mapping Files
+
+To use file based role-mappings, you must configure the mappings in a
 YAML file and copy it to each node in the cluster. Tools like Puppet or Chef can
 help with this.
 
@@ -26,20 +258,20 @@ are values. The mappings can have a many-to-many relationship. When you map role
 to groups, the roles of a user in that group are the combination of the roles
 assigned to that group and the roles assigned to that user.
 
-[[ad-role-mapping]]
+==== Realm Specific Details
-The available roles are either added using the <<roles-management-api, Role Management APIs>>
+[float]
-or defined in the <<roles-management-file, roles file>>. To specify users and
+[[ldap-role-mapping]]
-groups in the role mappings, you use their _Distinguished Names_ (DNs). A DN is
+===== Active Directory and LDAP Realms
-a string that uniquely identifies the user or group, for example
+To specify users and groups in the role mappings, you use their
-`"cn=John Doe,cn=contractors,dc=example,dc=com"`.
+_Distinguished Names_ (DNs). A DN is a string that uniquely identifies the user
+or group, for example `"cn=John Doe,cn=contractors,dc=example,dc=com"`.
 
 NOTE: {security} only supports Active Directory security groups. You cannot map
       distribution groups to roles.
 
-[[ldap-role-mapping]]
+For example, the following snippet uses the file-based method to map the
-For example, the following snippet maps the `admins` group to the `monitoring`
+`admins` group to the `monitoring` role and map the `John Doe` user, the
-role and maps the `John Doe` user, the `users` group, and the `admins` group to
+`users` group, and the `admins` group to the `user` role.
-the `user` role.
 
 [source, yaml]
 ------------------------------------------------------------
@@ -54,9 +286,41 @@ user:
 <2> The distinguished name of an LDAP group or an Active Directory security group.
 <3> The distinguished name of an LDAP or Active Directory user.
 
+We can use the role-mapping API to define equivalent mappings as follows:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/admins
+{
+  "roles" : [ "monitoring", "user" ],
+  "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+// TEST
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/basic_users
+{
+  "roles" : [ "user" ],
+  "rules" : { "any" : [
+      { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } },
+      { "field" : { "groups" : "cn=users,dc=example,dc=com" } }
+  ] },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+// TEST
+
+[float]
 [[pki-role-mapping]]
-PKI realms only support mapping users to roles, as there is no notion of a group
+===== PKI Realms
-in PKI. For example:
+PKI realms support mapping users to roles, but you cannot map groups as
+the PKI realm has no notion of a group.
+
+This is an example using a file-based mapping:
 
 [source, yaml]
 ------------------------------------------------------------
@@ -65,3 +329,28 @@ monitoring:
 user:
   - "cn=John Doe,ou=example,o=com"
 ------------------------------------------------------------
+
+And the equivalent mappings using the API:
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/admin_user
+{
+  "roles" : [ "monitoring" ],
+  "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+// TEST
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/security/role_mapping/basic_user
+{
+  "roles" : [ "user" ],
+  "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } },
+  "enabled": true
+}
+--------------------------------------------------
+// CONSOLE
+// TEST

docs/en/settings/security-settings.asciidoc

@@ -221,8 +221,8 @@ the filter.  If not set, the user DN is passed into the filter. Defaults to Empt
 
 `unmapped_groups_as_roles`::                
 Takes a boolean variable. When this element is set to `true`, the names of any 
-unmapped LDAP groups are used as role names and assigned to the user. Defaults
+LDAP groups that are not referenced in a role-mapping _file_ are used as role
-to `false`.
+names and assigned to the user. Defaults to `false`.
 
 `files.role_mapping`::               
 The <<security-files-location,location>> for the <<ldap-role-mapping, 
@@ -234,6 +234,10 @@ Boolean value that specifies whether Securityshould follow referrals returned
 by the LDAP server. Referrals are URLs returned by the server that are to be 
 used to continue the LDAP operation (e.g. search). Defaults to `true`.
 
+`metadata`::
+A list of additional LDAP attributes that should be loaded from the
+LDAP server and stored in the authenticated user's metadata field.
+
 `timeout.tcp_connect`::
 The TCP connect timeout period for establishing an LDAP connection.
 An `s` at the end indicates seconds, or `ms` indicates milliseconds.
@@ -331,12 +335,12 @@ The domain name of Active Directory. The cluster can derive the URL and
 otherwise specified. Required.
 
 `unmapped_groups_as_roles`::                                                         
-Takes a boolean variable. When this element is set to `true`, the names of 
+Takes a boolean variable. When this element is set to `true`, the names of any
-any unmapped groups and the user's relative distinguished name are used as 
+LDAP groups that are not referenced in a role-mapping _file_ are used as role
-role names and assigned to the user. Defaults to `false`.
+names and assigned to the user. Defaults to `false`.
 
 `files.role_mapping`::         
-The <<security-files-location,location>> for the <<ad-role-mapping, YAML 
+The <<security-files-location,location>> for the <<ldap-role-mapping, YAML
 role mapping configuration file>>. Defaults to  `CONFIG_DIR/x-pack/role_mapping.yml`. 
 
 `user_search.base_dn`::        
@@ -383,7 +387,11 @@ Specifies whether the group search should be `sub_tree`, `one_level` or
 `base` specifies that the `base_dn` is a group object, and that it is 
 the only group considered. Defaults to `sub_tree`.
 
-`timeout.tcp_connect`::         
+`metadata`::
+A list of additional LDAP attributes that should be loaded from the
+LDAP server and stored in the authenticated user's metadata field.
+
+`timeout.tcp_connect`::
 The TCP connect timeout period for establishing an LDAP connection.  
 An `s` at the end indicates seconds, or `ms` indicates milliseconds.
 Defaults to `5s` (5 seconds ).

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

@@ -1,6 +1,6 @@
 {
   "xpack.security.delete_role_mapping": {
-    "documentation": "Deletes a native role mapping (Documentation WIP)",
+    "documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-delete-role-mapping",
     "methods": [ "DELETE" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",

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

@@ -1,6 +1,6 @@
 {
   "xpack.security.get_role_mapping": {
-    "documentation": "Retrieves a native role mapping (Documentation WIP)",
+    "documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-get-role-mapping",
     "methods": [ "GET" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",

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

@@ -1,6 +1,6 @@
 {
   "xpack.security.put_role_mapping": {
-    "documentation": "Stores a native role mapping (Documentation WIP)",
+    "documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-put-role-mapping",
     "methods": [ "PUT", "POST" ],
     "url": {
       "path": "/_xpack/security/role_mapping/{name}",