[DOCS] Move security APIs to Elasticsearch Ref (elastic/x-pack-elasticsearch#1877)

* [DOCS] Move security APIs to Elasticsearch Ref

* [DOCS] Update links to security APIs

* [DOCS] Fix link to security APIs

Original commit: elastic/x-pack-elasticsearch@d7a9d3f1ab

docs/en/rest-api/index.asciidoc

@@ -10,7 +10,7 @@ directly to configure and access {xpack} features.
 * <<info-api, Info API>>
 * Graph <<graph-explore-api, Explore API>>
 * <<ml-apis, Machine Learning APIs>>
-* {xpack-ref}/security-api.html[Security APIs]
+* <<security-api,Security APIs>>
 * <<watcher-api, Watcher APIs>>
 --
 
@@ -18,6 +18,6 @@ directly to configure and access {xpack} features.
 include::info.asciidoc[]
 include::graph/explore.asciidoc[]
 include::ml-api.asciidoc[]
-// include::security.asciidoc[]
+include::security.asciidoc[]
 include::watcher.asciidoc[]
-include::defs.asciidoc[]
+include::defs.asciidoc[]

docs/en/rest-api/security.asciidoc

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api]]
 == Security APIs
 

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-authenticate]]
 === Authenticate API
 

docs/en/rest-api/security/change-password.asciidoc

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-change-password]]
 === Change Password API
 

docs/en/rest-api/security/clear-cache.asciidoc

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-clear-cache]]
 === Clear Cache API
 
@@ -29,4 +30,5 @@ POST _xpack/security/realm/default_file,ldap1/_clear_cache
 ------------------------------------------------------------
 // CONSOLE
 
-For more information, see <<controlling-user-cache, Controlling the User Cache>>.
+For more information, see 
+{xpack-ref}/controlling-user-cache.html[Controlling the User Cache].

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-privileges]]
 === Privilege APIs
 
@@ -6,9 +7,10 @@
 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. 
+All users can use this API, but only to determine their own privileges.
-To check the privileges of other users, you must use the
+To check the privileges of other users, you must use the run as feature. For
-<<run-as-privilege,run as>> feature.
+more information, see 
+{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
 
 To check you privileges, submit a GET request to the
 `_xpack/security/user/_has_privileges` endpoint:
@@ -22,7 +24,7 @@ GET _xpack/security/user/_has_privileges
     {
       "names": [ "suppliers", "products" ],
       "privileges": [ "read" ]
-    }, 
+    },
     {
       "names": [ "inventory" ],
       "privileges" : [ "read", "write" ]

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-role-mapping]]
 === Role Mapping APIs
 
@@ -6,7 +7,7 @@ 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.
+ not affect the behavior 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>`

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-roles]]
 === Role Management APIs
 
@@ -40,7 +41,8 @@ Within the `metadata` object, keys beginning with `_` are reserved for system
 usage.
 
 The `field_security` and `query` fields are both optional. They are used to
-implement <<field-and-document-access-control, Field and Document Level Security>>.
+implement field and document level security. For more information, see
+{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
 
 A successful call returns a JSON structure that shows whether the role has been
 created or updated.

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-tokens]]
 === Token Management APIs
 

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

@@ -1,3 +1,4 @@
+[role="xpack"]
 [[security-api-users]]
 === User Management APIs
 
@@ -10,9 +11,9 @@ To add a user, submit a PUT or POST request to the `/_xpack/security/user/<usern
 endpoint.
 
 [[username-validation]]
-NOTE: Usernames must be at least 1 and no more than 1024 characters. They can 
+NOTE: Usernames must be at least 1 and no more than 1024 characters. They can
-      contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, 
+      contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces,
-      punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. 
+      punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
       Leading or trailing whitespace is not allowed.
 
 [source,js]

docs/en/rest-api/xindex.asciidoc

@@ -1,18 +0,0 @@
-[[xpack-api]]
-= {xpack} APIs
-
-[partintro]
---
-{xpack} exposes REST APIs that are used by the UI components and can be called
-directly to configure and access {xpack} features.
-
-* {ref}/info-api[Info API]
-* {ref}/graph-explore-api[Graph APIs]
-* {ref}/ml-apis.html[Machine Learning APIs]
-* {ref}/ml-api-definitions.html[Definitions]
-* <<security-api, Security APIs>>
-* {ref}/watcher-api.html[Watcher APIs]
-
---
-
-include::security.asciidoc[]

docs/en/security/authentication.asciidoc

@@ -40,7 +40,8 @@ any changes you have applied will be lost.
 Although they share the same API, the built-in users are separate and distinct
 from users managed by the <<native-realm, native realm>>. Disabling the native
 realm will not have any effect on the built-in users. The built-in users can
-be disabled individually, using the <<security-api-users, user management api>>.
+be disabled individually, using the
+{ref}/security-api-users.html[user management API].
 
 [float]
 [[reset-built-in-user-passwords]]
@@ -50,7 +51,7 @@ be disabled individually, using the <<security-api-users, user management api>>.
 You must reset the default passwords for all built-in users, and then
 <<disabling-default-password, disable default password support>>.
 You can update passwords from the *Management > Users* UI in Kibana or with the
-<<security-api-reset-user-password, Reset Password API>>:
+{ref}/security-api-reset-user-password.html[Reset Password API]:
 
 [source,js]
 ---------------------------------------------------------------------

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

@@ -71,9 +71,9 @@ xpack:
 <3> When this option is enabled, Active Directory groups are automatically mapped
     to roles of the same name.
 +
-IMPORTANT: When you configure realms in `elasticsearch.yml`, only the 
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
-realms you specify are used for authentication. If you also want to use the 
+realms you specify are used for authentication. If you also want to use the
-`native` or `file` realms, you must include them in the realm chain. 
+`native` or `file` realms, you must include them in the realm chain.
 
 . Restart Elasticsearch.
 
@@ -288,7 +288,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 {ref}/security-api-role-mapping.html[role-mapping API], 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.
@@ -355,7 +355,7 @@ For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
 ==== User Metadata in Active Directory Realms
 When a user is authenticated via an Active Directory realm, the following
 properties are populated in the user's _metadata_. This metadata is returned in the
-<<security-api-authenticate,authenticate API>>, and can be used with
+{ref}/security-api-authenticate.html[authenticate API], and can be used with
 <<templating-role-query, templated queries>> in roles.
 
 |=======================

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

@@ -72,9 +72,9 @@ xpack:
           unmapped_groups_as_roles: false
 ------------------------------------------------------------
 +
-IMPORTANT: When you configure realms in `elasticsearch.yml`, only the 
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
-realms you specify are used for authentication. If you also want to use the 
+realms you specify are used for authentication. If you also want to use the
-`native` or `file` realms, you must include them in the realm chain. 
+`native` or `file` realms, you must include them in the realm chain.
 
 . Restart Elasticsearch
 
@@ -278,7 +278,7 @@ failover and load balancing modes of operation.
                                                         impact, `bind_dn` is not exposed via the
                                                         {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
 | `bind_password`                          | no       | The password for the user that is used to bind to the
-                                                        LDAP. Due to its potential security impact,  
+                                                        LDAP. Due to its potential security impact,
                                                         `bind_password` is not exposed via the
                                                         {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
 | `user_search.base_dn`                    | yes      | Specifies a container DN to search for users.
@@ -337,7 +337,7 @@ systems in the organization.
 
 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
-<<security-api-role-mapping, role-mapping API>>, or by using a file stored
+{ref}/security-api-role-mapping.html[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.
@@ -395,7 +395,7 @@ For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
 ==== 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
+{ref}/security-api-authenticate.html[authenticate API], and can be used with
 <<templating-role-query, templated queries>> in roles.
 
 |=======================

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

@@ -13,9 +13,9 @@ The native realm is added to the realm chain by default. You don't need to
 explicitly configure a native realm to manage users through the REST APIs.
 
 
-IMPORTANT: When you configure realms in `elasticsearch.yml`, only the 
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
-realms you specify are used for authentication. To use the 
+realms you specify are used for authentication. To use the
-`native` realm as a fallback, you must include it in the realm chain. 
+`native` realm as a fallback, you must include it in the realm chain.
 
 You can, however, configure options for the `native` realm in the
 `xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly
@@ -87,7 +87,8 @@ xpack:
 [[managing-native-users]]
 ==== Managing Native Users
 
-You manage users in the `native` realm through the <<security-api-users, user API>>.
+You manage users in the `native` realm through the
+{ref}/security-api-users.html[user API].
 
 [[migrating-from-file]]
 NOTE: To migrate file-based users to the `native` realm, use the
@@ -100,9 +101,9 @@ NOTE: To migrate file-based users to the `native` realm, use the
 To add a user, submit a PUT or POST request to the `/_xpack/security/user/<username>`
 endpoint.
 
-Usernames must be at least 1 and no more than 1024 characters. They can 
+Usernames must be at least 1 and no more than 1024 characters. They can
-contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and 
+contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and
-printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. 
+printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
 Leading or trailing whitespace is not allowed.
 
 [source,js]

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

@@ -46,9 +46,9 @@ With this configuration, any certificate trusted by the SSL/TLS layer is accepte
 for authentication. The username is the common name (CN) extracted from the DN
 of the certificate.
 +
-IMPORTANT: When you configure realms in `elasticsearch.yml`, only the 
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
-realms you specify are used for authentication. If you also want to use the 
+realms you specify are used for authentication. If you also want to use the
-`native` or `file` realms, you must include them in the realm chain. 
+`native` or `file` realms, you must include them in the realm chain.
 +
 If you want to use something other than the CN of the DN as the username, you
 can specify a regex to extract the desired username. For example, the regex in
@@ -118,7 +118,7 @@ xpack:
 ==== Mapping Roles for PKI Users
 
 You map roles for PKI users through the
-<<security-api-role-mapping, role-mapping API>>, or by using a file stored on
+{ref}/security-api-role-mapping.html[role-mapping API], 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.

docs/en/security/authentication/user-cache.asciidoc

@@ -35,7 +35,8 @@ setting the `cache_hash_algo` setting to any of the following:
 [[cache-eviction-api]]
 ==== Evicting Users from the Cache
 
-{security} exposes a <<security-api-clear-cache, Clear Cache API>> you can use
+{security} exposes a
+{ref}/security-api-clear-cache.html[Clear Cache API] you can use
 to force the eviction of cached users. For example, the following request evicts
 all users from the `ad1` realm:
 

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

@@ -27,7 +27,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
-<<security-api-role-mapping, role mapping API>>.
+{ref}/security-api-role-mapping.html[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

docs/en/security/how-security-works.asciidoc

@@ -27,7 +27,8 @@ _realms_. {security} provides the following built-in realms:
 | `native`            | | | An internal realm where users are stored in a dedicated
                             Elasticsearch index. With this realm, users are
                             authenticated by usernames and passwords. The users
-                            are managed via the <<security-api-users,User Management API>>.
+                            are managed via the
+                            {ref}/security-api-users.html[User Management API].
 
 | `ldap`              | | | A realm that uses an external LDAP server to authenticate
                             the users. With this realm, users are authenticated by
@@ -124,9 +125,9 @@ to, from and within the cluster. This support accounts for:
 For more information, see <<encrypting-communications, Encrypting Communications>>.
 
 {security} also enables you to <<ip-filtering, configure IP Filters>> which can
-be seen as a light mechanism for node/client authentication. With IP Filtering 
+be seen as a light mechanism for node/client authentication. With IP Filtering
-you can restrict the nodes and clients that can connect to the cluster based 
+you can restrict the nodes and clients that can connect to the cluster based
-on their IP addresses. The IP filters configuration provides whitelisting 
+on their IP addresses. The IP filters configuration provides whitelisting
 and blacklisting of IPs, subnets and DNS domains.
 
 

docs/en/security/reference.asciidoc

@@ -3,7 +3,7 @@
 * <<security-privileges, Security Privileges>>
 * {ref}/security-settings.html[Security Settings]
 * <<security-files, Security Files>>
-* <<security-api, Security API>>
+* {ref}/security-api.html[Security API]
 
 include::reference/privileges.asciidoc[]
 

docs/en/security/release-notes.asciidoc

@@ -82,7 +82,8 @@ April 4, 2016
 March 30, 2016
 
 .New Features
-* <<native-realm,Native realm>> with support for <<security-api-users,user management APIs>>.
+* <<native-realm,Native realm>> with support for
+{ref}/security-api-users.html[user management APIs].
 * <<security-api-roles,Role management APIs>> have been added.
 
 .Bug Fixes
@@ -199,7 +200,7 @@ August 10, 2015
 
 .Bug Fixes
 * When using the <<ldap-user-search,LDAP user search>> mechanism, connection errors during startup no longer cause the node to stop.
-* The <<security-api-clear-cache,Clear Cache API>> no longer generates invalid JSON.
+* The {ref}/security-api-clear-cache.html[Clear Cache API] no longer generates invalid JSON.
 * The <<audit-index,index output for auditing>> starts properly when forwarding the audit events to a remote cluster and uses
 the correct user to index the audit events.