[6.7][DOCS] Adds security content in Elasticsearch Reference

docs/reference/index.asciidoc

@@ -63,7 +63,7 @@ include::rollup/index.asciidoc[]
 
 include::frozen-indices.asciidoc[]
 
-include::security/index.asciidoc[]
+include::{xes-repo-dir}/security/index.asciidoc[]
 
 include::{xes-repo-dir}/watcher/index.asciidoc[]
 

docs/reference/settings/security-settings.asciidoc

@@ -69,8 +69,7 @@ See <<password-hashing-algorithms>>. Defaults to `bcrypt`.
 [[anonymous-access-settings]]
 ==== Anonymous access settings
 You can configure the following anonymous access settings in
-`elasticsearch.yml`.  For more information, see {stack-ov}/anonymous-access.html[
-Enabling anonymous access].
+`elasticsearch.yml`.  For more information, see <<anonymous-access>>.
 
 `xpack.security.authc.anonymous.username`::
 The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`.
@@ -120,8 +119,7 @@ Defaults to `48h` (48 hours).
 
 You can set the following document and field level security
 settings in `elasticsearch.yml`. For more information, see
-{stack-ov}/field-and-document-access-control.html[Setting up document and field
-level security].
+<<field-and-document-access-control>>.
 
 `xpack.security.dls_fls.enabled`::
 Set to `false` to prevent document and field level security
@@ -206,7 +204,7 @@ xpack.security.authc.realms:
 ----------------------------------------
 
 The valid settings vary depending on the realm type. For more
-information, see {stack-ov}/setting-up-authentication.html[Setting up authentication].
+information, see <<setting-up-authentication>>.
 
 [float]
 [[ref-realm-settings]]
@@ -245,8 +243,8 @@ Defaults to `ssha256`.
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-users-settings]]
@@ -261,7 +259,7 @@ the following settings:
 `cache.ttl`::
 The time-to-live for cached user entries. A user and a hash of its credentials 
 are cached for this configured period of time. Defaults to `20m`. Specify values 
-using the standard {es} {ref}/common-options.html#time-units[time units].
+using the standard {es} <<time-units,time units>>.
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -274,8 +272,8 @@ user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-ldap-settings]]
@@ -326,14 +324,14 @@ The DN template that replaces the user name with the string `{0}`.
 This setting is multivalued; you can specify multiple user contexts.
 Required to operate in user template mode. If `user_search.base_dn` is specified, 
 this setting is not valid. For more information on
-the different modes, see {stack-ov}/ldap-realm.html[LDAP realms].
+the different modes, see <<ldap-realm>>.
 
 `authorization_realms`::
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the LDAP realm does not perform role mapping and
 instead loads the user from the listed realms. The referenced realms are
 consulted in the order that they are defined in this list.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>.
 +
 --
 NOTE: If any settings starting with `user_search` are specified, the 
@@ -350,7 +348,7 @@ to `memberOf`.
 Specifies a container DN to search for users. Required
 to operated in user search mode. If `user_dn_templates` is specified, this 
 setting is not valid. For more information on
-the different modes, see {stack-ov}/ldap-realm.html[LDAP realms].
+the different modes, see <<ldap-realm>>.
 
 `user_search.scope`::
 The scope of the user search. Valid values are `sub_tree`, `one_level` or
@@ -423,12 +421,12 @@ the filter.  If not set, the user DN is passed into the filter. Defaults to Empt
 If set to `true`, the names of any unmapped LDAP groups are used as role names 
 and assigned to the user. A group is considered to be _unmapped_ if it is not 
 referenced in a
-{stack-ov}/mapping-roles.html#mapping-roles-file[role-mapping file]. API-based 
+<<mapping-roles-file,role-mapping file>>. API-based 
 role mappings are not considered. Defaults to `false`.
 
 `files.role_mapping`::
-The <<security-files,location>> for the {stack-ov}/mapping-roles.html#mapping-roles[
-YAML role mapping configuration file]. Defaults to
+The <<security-files,location>> for the
+<<mapping-roles,YAML role mapping configuration file>>. Defaults to
 `ES_PATH_CONF/role_mapping.yml`.
 
 `follow_referrals`::
@@ -545,8 +543,8 @@ in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 [[ref-ad-settings]]
@@ -786,7 +784,7 @@ Java Cryptography Architecture documentation]. Defaults to the value of
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
 credentials are cached for this configured period of time. Use the
-standard Elasticsearch {ref}/common-options.html#time-units[time units]).
+standard Elasticsearch <<time-units,time units>>).
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -799,8 +797,8 @@ the in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssh
 
 `authentication.enabled`:: If set to `false`, disables authentication support in
 this realm, so that it only supports user lookups.
-(See the {stack-ov}/run-as-privilege.html[run as] and
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] features).
+(See the <<run-as-privilege,run as>> and
+<<authorization_realms,authorization realms>> features).
 Defaults to `true`.
 
 `follow_referrals`::
@@ -841,19 +839,19 @@ for SSL. This setting cannot be used with `certificate_authorities`.
 
 `files.role_mapping`::
 Specifies the <<security-files,location>> of the
-{stack-ov}/mapping-roles.html[YAML role  mapping configuration file].
+<<mapping-roles,YAML role  mapping configuration file>>.
 Defaults to `ES_PATH_CONF/role_mapping.yml`.
 
 `authorization_realms`::
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the PKI realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>.
 
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
 credentials are cached for this period of time. Use the
-standard {es} {ref}/common-options.html#time-units[time units]).
+standard {es} <<time-units,time units>>).
 Defaults to `20m`.
 
 `cache.max_users`::
@@ -973,7 +971,7 @@ provided by the SAML attributes. Defaults to `true`.
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the SAML realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm] 
+See <<authorization_realms>>.
 
 `allowed_clock_skew`::
 The maximum amount of skew that can be tolerated between the IdP's clock and the
@@ -987,7 +985,7 @@ authenticate the current user. The Authentication Context of the corresponding
 authentication response should contain at least one of the requested values.
 +
 For more information, see
-{stack-ov}/saml-guide-authentication.html#req-authn-context[Requesting specific authentication methods].
+<<req-authn-context>>.
 
 [float]
 [[ref-saml-signing-settings]]
@@ -1221,7 +1219,7 @@ cache at any given time. Defaults to 100,000.
 The names of the realms that should be consulted for delegated authorization.
 If this setting is used, then the Kerberos realm does not perform role mapping and
 instead loads the user from the listed realms.
-See {stack-ov}/realm-chains.html#authorization_realms[Delegating authorization to another realm]
+See <<authorization_realms>>.
 
 [float]
 [[load-balancing]]
@@ -1264,7 +1262,7 @@ endif::[]
 
 You can configure the following TLS/SSL settings in
 `elasticsearch.yml`. For more information, see
-{stack-ov}/encrypting-communications.html[Encrypting communications]. These
+<<encrypting-communications>>. These
 settings are used unless they have been overridden by more specific
 settings such as those for HTTP or Transport.
 
@@ -1422,7 +1420,7 @@ keystore files. See <<fips-140-compliance>>.
 [[pkcs12-truststore-note]]
 [NOTE]
 Storing trusted certificates in a PKCS#12 file, although supported, is
-uncommon in practice. The {ref}/certutil.html[`elasticsearch-certutil`] tool,
+uncommon in practice. The <<certutil,`elasticsearch-certutil`>> tool,
 as well as Java's `keytool`, are designed to generate PKCS#12 files that
 can be used both as a keystore and as a truststore, but this may not be the
 case for container files that are created using other tools. Usually,
@@ -1509,7 +1507,7 @@ See also <<remote-audit-settings>>.
 [[ip-filtering-settings]]
 ==== IP filtering settings
 
-You can configure the following settings for {stack-ov}/ip-filtering.html[IP filtering].
+You can configure the following settings for <<ip-filtering,IP filtering>>.
 
 `xpack.security.transport.filter.allow`::
 List of IP addresses to allow.

x-pack/docs/en/security/auditing/event-types.asciidoc

@@ -18,7 +18,7 @@ The following is a list of the events that can be generated:
                                           realm type.
 | `access_denied`                   | | | Logged when an authenticated user attempts to execute
                                           an action they do not have the necessary
-                                          <<security-reference, privilege>> to perform.
+                                          <<security-privileges,privilege>> to perform.
 | `access_granted`                  | | | Logged when an authenticated user attempts to execute
                                           an action they have the necessary privilege to perform.
                                           When the `system_access_granted` event is included, all system
@@ -28,7 +28,7 @@ The following is a list of the events that can be generated:
                                           another user that they have the necessary privileges to do.
 | `run_as_denied`                   | | | Logged when an authenticated user attempts to <<run-as-privilege, run as>>
                                           another user action they do not have the necessary
-                                          <<security-reference, privilege>> to do so.
+                                          <<security-privileges,privilege>> to do so.
 | `tampered_request`                | | | Logged when the {security-features} detect that the request has
                                           been tampered with. Typically relates to `search/scroll`
                                           requests when the scroll ID is believed to have been

x-pack/docs/en/security/auditing/index.asciidoc

@@ -1,18 +1,7 @@
 
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/overview.asciidoc
 include::overview.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/event-types.asciidoc
 include::event-types.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/output-logfile.asciidoc
 include::output-logfile.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/output-index.asciidoc
 include::output-index.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/auditing-search-queries.asciidoc
 include::auditing-search-queries.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc
 include::forwarding-logs.asciidoc[]

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

@@ -0,0 +1,81 @@
+[role="xpack"]
+[[active-directory-realm]]
+=== Active Directory user authentication
+
+You can configure {security} to communicate with Active Directory to authenticate
+users. To integrate with Active Directory, you configure an `active_directory`
+realm and map Active Directory users and groups to {security} roles in the
+<<mapping-roles, role mapping file>>.
+
+See {ref}/configuring-ad-realm.html[Configuring an Active Directory Realm].
+
+{security} uses LDAP to communicate with Active Directory, so `active_directory`
+realms are similar to <<ldap-realm, `ldap` realms>>. Like LDAP directories,
+Active Directory stores users and groups hierarchically. The directory's
+hierarchy is built from containers such as the _organizational unit_ (`ou`),
+_organization_ (`o`), and _domain controller_ (`dc`).
+
+The path to an entry is a _Distinguished Name_ (DN) that uniquely identifies a
+user or group. User and group names typically have attributes such as a
+_common name_ (`cn`) or _unique ID_ (`uid`). A DN is specified as a string, for
+example `"cn=admin,dc=example,dc=com"` (white spaces are ignored).
+
+{security} only supports Active Directory security groups. You cannot map
+distribution groups to roles.
+
+NOTE: When you use Active Directory for authentication, the username entered by
+      the user is expected to match the `sAMAccountName` or `userPrincipalName`,
+      not the common name.
+
+The Active Directory realm authenticates users using an LDAP bind request. After
+authenticating the user, the realm then searches to find the user's entry in
+Active Directory. Once the user has been found, the Active Directory realm then
+retrieves the user's group memberships from the `tokenGroups` attribute on the
+user's entry in Active Directory.
+
+[[ad-load-balancing]]
+==== Load balancing and failover
+The `load_balance.type` setting can be used at the realm level to configure how
+{security} should interact with multiple Active Directory servers. Two modes of
+operation are supported: failover and load balancing.
+
+See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
+
+[[ad-settings]]
+==== Active Directory realm settings
+
+See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings].
+
+[[mapping-roles-ad]]
+==== Mapping Active Directory users and groups to roles
+
+See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm]. 
+
+[[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 the user's _metadata_:
+
+|=======================
+| 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).
+|=======================
+
+This metadata is returned in the 
+{ref}/security-api-authenticate.html[authenticate API] and can be used with
+//TEMPORARILY OMIT:<<templating-role-query,
+templated queries
+//>>
+in roles.
+
+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
+
+See 
+{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory].