Outstanding docs for 5.4 changes (elastic/x-pack-elasticsearch#1280)

Docs for security features in 5.4

- `has_privileges` API
-  ldap metadata.

Original commit: elastic/x-pack-elasticsearch@22c733c814

docs/en/rest-api/security.asciidoc

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

docs/en/rest-api/security/authenticate.asciidoc

@@ -14,7 +14,7 @@ GET _xpack/security/_authenticate
 // CONSOLE
 
 A successful call returns a JSON structure that shows what roles are assigned
-to the user.
+to the user as well as any assigned metadata.
 
 [source,js]
 --------------------------------------------------
@@ -23,6 +23,9 @@ to the user.
   "roles": [
     "admin",
     "kibana4"
-  ]
+  ],
+  "metadata" : {
+    "employee_id": "8675309"
+  }
 }
 --------------------------------------------------

docs/en/rest-api/security/privileges.asciidoc

@@ -0,0 +1,62 @@
+[[security-api-privileges]]
+=== Privilege APIs
+
+[[security-api-has-privilege]]
+
+The `has_privileges` API allows you to determine whether the logged in user has
+a specified list of privileges.
+
+All users can use this API, but only to determine their own privileges. 
+To check the privileges of other users, you must use the
+<<run-as-privilege,run as>> feature.
+
+To check you privileges, submit a GET request to the
+`_xpack/security/user/_has_privileges` endpoint:
+
+[source,js]
+--------------------------------------------------
+GET _xpack/security/user/_has_privileges
+{
+  "cluster": [ "monitor", "manage" ],
+  "index" : [
+    {
+      "names": [ "suppliers", "products" ],
+      "privileges": [ "read" ]
+    }, 
+    {
+      "names": [ "inventory" ],
+      "privileges" : [ "read", "write" ]
+    }
+  ]
+}
+--------------------------------------------------
+// CONSOLE
+
+A successful call returns a JSON structure that shows whether each specified
+privilege is assigned to the user
+
+[source,js]
+--------------------------------------------------
+{
+  "username": "rdeniro",
+  "has_all_requested" : false,
+  "cluster" : {
+    "monitor" : true,
+    "manage" : false
+  },
+  "index" : {
+    "suppliers" : {
+      "read" : true
+    },
+    "products" : {
+      "read" : true
+    },
+    "inventory" : {
+      "read" : true,
+      "write" : false
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/"rdeniro"/"$body.username"/]
+// TESTRESPONSE[s/: false/: true/]

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

@@ -304,6 +304,22 @@ user:
 
 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
+<<security-api-authenticate,authenticate API>>, and can be used with
+<<templating-role-query, templated queries>> in roles.
+
+|=======================
+| Field               | Description
+| `ldap_dn`           | The distinguished name of the user.
+| `ldap_groups`       | The distinguished name of each of the groups that were
+                        resolved for the user (regardless of whether those
+                        groups were mapped to a role).
+|=======================
+
+
 [[active-directory-ssl]]
 ==== Setting up SSL Between Elasticsearch and Active Directory
 

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

@@ -353,6 +353,21 @@ user:
 
 For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
 
+[[ldap-user-metadata]]
+==== User Metadata in LDAP Realms
+When a user is authenticated via an LDAP realm, the following properties are
+populated in 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.
+
+|=======================
+| Field               | Description
+| `ldap_dn`           | The distinguished name of the user.
+| `ldap_groups`       | The distinguished name of each of the groups that were
+                        resolved for the user (regardless of whether those
+                        groups were mapped to a role).
+|=======================
+
 [[ldap-ssl]]
 ==== Setting up SSL Between Elasticsearch and LDAP