[6.4][DOCS] Copies security source files from stack-docs

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

@@ -0,0 +1,78 @@
+[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
+<<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].

x-pack/docs/en/security/authentication/built-in-users.asciidoc

@@ -0,0 +1,157 @@
+[role="xpack"]
+[[built-in-users]]
+=== Built-in users
+
+{security} provides built-in user credentials to help you get up and running.
+These users have a fixed set of privileges and cannot be authenticated until their
+passwords have been set. The `elastic` user can be used to
+<<set-built-in-user-passwords,set all of the built-in user passwords>>.
+
+`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
+`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
+`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.
+`beats_system`:: The user the Beats use when storing monitoring information in Elasticsearch.
+
+
+[float]
+[[built-in-user-explanation]]
+==== How the built-in users work
+These built-in users are stored within a special `.security` index managed by
+{security}.
+This means that, if the password is changed, or a user is disabled, then that
+change is automatically reflected on each node in the cluster. It also means
+that if your `.security` index is deleted, or restored from a snapshot, then
+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
+{ref}/security-api-disable-user.html[disable users API].
+
+[float]
+[[bootstrap-elastic-passwords]]
+==== The Elastic bootstrap password
+
+When you install {es}, if the `elastic` user does not already have a password,
+it uses a default bootstrap password. The bootstrap password is a transient
+password that enables you to run the tools that set all the built-in user passwords.
+
+By default, the bootstrap password is derived from a randomized `keystore.seed`
+setting, which is added to the keystore during installation. You do not need
+to know or change this bootstrap password. If you have defined a
+`bootstrap.password` setting in the keystore, however, that value is used instead.
+For more information about interacting with the keystore, see
+{ref}/secure-settings.html[Secure Settings].
+
+NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
+in particular for the `elastic` user, there is no further use for the bootstrap
+password.
+
+[float]
+[[set-built-in-user-passwords]]
+==== Setting built-in user passwords
+
+You must set the passwords for all built-in users.
+
+The +elasticsearch-setup-passwords+ tool is the simplest method to set the
+built-in users' passwords for the first time. It uses the `elastic` user's
+bootstrap password to run user management API requests. For example, you can run
+the command in an "interactive" mode, which prompts you to enter new passwords
+for the `elastic`, `kibana`, `logstash_system`, and `beats_system` users:
+
+[source,shell]
+--------------------------------------------------
+bin/elasticsearch-setup-passwords interactive
+--------------------------------------------------
+
+For more information about the command options, see
+{ref}/setup-passwords.html[elasticsearch-setup-passwords].
+
+IMPORTANT: After you set a password for the `elastic` user, the bootstrap
+password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
+command a second time.
+
+Alternatively, you can set the initial passwords for the built-in users by using
+the *Management > Users* page in {kib} or the
+{ref}/security-api-change-password.html[Change Password API]. These methods are
+more complex. You must supply the `elastic` user and its bootstrap password to
+log into {kib} or run the API. This requirement means that you cannot use the
+default bootstrap password that is derived from the `keystore.seed` setting.
+Instead, you must explicitly set a `bootstrap.password` setting in the keystore
+before you start {es}. For example, the following command prompts you to enter a
+new bootstrap password:
+
+[source,shell]
+----------------------------------------------------
+bin/elasticsearch-keystore add "bootstrap.password"
+----------------------------------------------------
+
+You can then start {es} and {kib} and use the `elastic` user and bootstrap
+password to log into {kib} and change the passwords. Alternatively, you can
+submit Change Password API requests for each built-in user. These methods are
+better suited for changing your passwords after the initial setup is complete,
+since at that point the bootstrap password is no longer required.
+
+[float]
+[[add-built-in-user-passwords]]
+==== Adding Built-in User Passwords To {kib}, Logstash, and Beats
+
+After the `kibana` user password is set, you need to update the {kib} server
+with the new password by setting `elasticsearch.password` in the `kibana.yml`
+configuration file:
+
+[source,yaml]
+-----------------------------------------------
+elasticsearch.password: kibanapassword
+-----------------------------------------------
+
+The `logstash_system` user is used internally within Logstash when
+monitoring is enabled for Logstash.
+
+To enable this feature in Logstash, you need to update the Logstash
+configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
+the `logstash.yml` configuration file:
+
+[source,yaml]
+----------------------------------------------------------
+xpack.monitoring.elasticsearch.password: logstashpassword
+----------------------------------------------------------
+
+If you have upgraded from an older version of Elasticsearch,
+the `logstash_system` user may have defaulted to _disabled_ for security reasons.
+Once the password has been changed, you can enable the user via the following API call:
+
+[source,js]
+---------------------------------------------------------------------
+PUT _xpack/security/user/logstash_system/_enable
+---------------------------------------------------------------------
+// CONSOLE
+
+The `beats_system` user is used internally within Beats when monitoring is
+enabled for Beats.
+
+To enable this feature in Beats, you need to update the configuration for each
+of your beats to reference the correct username and password. For example:
+
+[source,yaml]
+----------------------------------------------------------
+xpack.monitoring.elasticsearch.username: beats_system
+xpack.monitoring.elasticsearch.password: beatspassword
+----------------------------------------------------------
+
+If you have upgraded from an older version of {es}, then you may not have set a
+password for the `beats_system` user. If this is the case, then you should use
+the *Management > Users* page in {kib} or the
+{ref}/security-api-change-password.html[Change Password API] to set a password
+for this user.
+
+[float]
+[[disabling-default-password]]
+==== Disabling default password functionality
+[IMPORTANT]
+=============================================================================
+This setting is deprecated. The elastic user no longer has a default password.
+The password must be set before the user can be used.
+See <<bootstrap-elastic-passwords>>.
+=============================================================================

x-pack/docs/en/security/authentication/file-realm.asciidoc

@@ -0,0 +1,27 @@
+[role="xpack"]
+[[file-realm]]
+=== File-based user authentication
+
+You can manage and authenticate users with the built-in `file` realm.
+With the `file` realm, users are defined in local files on each node in the cluster.
+
+IMPORTANT:  As the administrator of the cluster, it is your responsibility to
+            ensure the same users are defined on every node in the cluster.
+            {security} does not deliver any mechanism to guarantee this.
+
+The `file` realm is primarily supported to serve as a fallback/recovery realm. It
+is mostly useful in situations where all users locked themselves out of the system
+(no one remembers their username/password). In this type of scenarios, the `file`
+realm is your only way out - you can define a new `admin` user in the `file` realm
+and use it to log in and reset the credentials of all other users.
+
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
+realms you specify are used for authentication. To use the
+`file` realm as a fallback, you must include it in the realm chain.
+
+To define users, {security} provides the {ref}/users-command.html[users]
+command-line tool. This tool enables you to add and remove users, assign user
+roles, and manage user passwords.
+
+For more information, see 
+{ref}/configuring-file-realm.html[Configuring a file realm].

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

@@ -0,0 +1,20 @@
+
+include::overview.asciidoc[]
+include::built-in-users.asciidoc[]
+include::internal-users.asciidoc[]
+include::realms.asciidoc[]
+include::active-directory-realm.asciidoc[]
+include::file-realm.asciidoc[]
+include::ldap-realm.asciidoc[]
+include::native-realm.asciidoc[]
+include::pki-realm.asciidoc[]
+include::saml-realm.asciidoc[]
+include::kerberos-realm.asciidoc[]
+
+include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]
+
+include::{xes-repo-dir}/security/authentication/anonymous-access.asciidoc[]
+
+include::{xes-repo-dir}/security/authentication/user-cache.asciidoc[]
+
+include::{xes-repo-dir}/security/authentication/saml-guide.asciidoc[]

x-pack/docs/en/security/authentication/internal-users.asciidoc

@@ -0,0 +1,13 @@
+[role="xpack"]
+[[internal-users]]
+=== Internal users
+
+{security} has three _internal_ users (`_system`, `_xpack`, and `_xpack_security`)
+that are responsible for the operations that take place inside an {es} cluster.
+
+These users are only used by requests that originate from within the cluster.
+For this reason, they cannot be used to authenticate against the API and there
+is no password to manage or reset.
+
+From time-to-time you may find a reference to one of these users inside your
+logs, including <<auditing, audit logs>>.

x-pack/docs/en/security/authentication/kerberos-realm.asciidoc

@@ -0,0 +1,63 @@
+[role="xpack"]
+[[kerberos-realm]]
+=== Kerberos authentication
+
+You can configure {security} to support Kerberos V5 authentication,
+an industry standard protocol to authenticate users in {es}.
+
+NOTE: You cannot use the Kerberos realm to authenticate users in {kib}
+and on the transport network layer.
+
+To authenticate users with Kerberos, you need to
+{ref}/configuring-kerberos-realm.html[configure a Kerberos realm] and
+<<mapping-roles, map users to {security} roles>>.
+For more information on realm settings, see
+{ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+
+[[kerberos-terms]]
+==== Key concepts
+
+There are a few terms and concepts that you'll encounter when you're setting up 
+Kerberos realms:
+
+_kdc_::
+Key Distribution Center. A service that issues Kerberos tickets.
+
+_principal_::
+A Kerberos principal is a unique identity to which Kerberos can assign
+tickets. It can be used to identify a user or a service provided by a
+server.
++
+--
+Kerberos V5 principal names are of format `primary/instance@REALM`, where
+`primary` is a user name.
+
+`instance` is an optional string that qualifies the primary and is separated
+by a slash(`/`) from the primary. For a user, usually it is not used; for
+service hosts, it is the fully qualified domain name of the host.
+
+`REALM` is the Kerberos realm. Usually it is is the domain name in upper case.
+An example of a typical user principal is `[email protected]`. An example of 
+a typical service principal is `HTTP/[email protected]`.
+--
+
+_realm_::
+Realms define the administrative boundary within which the authentication server
+has authority to authenticate users and services.
+
+_keytab_::
+A file that stores pairs of principals and encryption keys.
+
+IMPORTANT: Anyone with read permissions to this file can use the
+credentials in the network to access other services so it is important
+to protect it with proper file permissions.
+
+_krb5.conf_::
+A file that contains Kerberos configuration information such as the default realm
+name, the location of Key distribution centers (KDC), realms information,
+mappings from domain names to Kerberos realms, and default configurations for
+realm session key encryption types.
+
+_ticket granting ticket (TGT)_::
+A TGT is an authentication ticket generated by the Kerberos authentication
+server. It contains an encrypted authenticator.