[DOCS] Removes duplicated authentication pages
This commit is contained in:
lcawl
parent
be55da18c2
commit
53357e7d14
|
|
@ -1,78 +0,0 @@
|
||||||
[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].
|
|
||||||
|
|
@ -1,157 +0,0 @@
|
||||||
[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-users.html[user management 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>>.
|
|
||||||
=============================================================================
|
|
||||||
|
|
@ -1,100 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[custom-realms]]
|
|
||||||
=== Integrating with other authentication systems
|
|
||||||
|
|
||||||
If you are using an authentication system that is not supported out-of-the-box
|
|
||||||
by {security}, you can create a custom realm to interact with it to authenticate
|
|
||||||
users. You implement a custom realm as an SPI loaded security extension
|
|
||||||
as part of an ordinary elasticsearch plugin.
|
|
||||||
|
|
||||||
[[implementing-custom-realm]]
|
|
||||||
==== Implementing a custom realm
|
|
||||||
|
|
||||||
Sample code that illustrates the structure and implementation of a custom realm
|
|
||||||
is provided in the https://github.com/elastic/shield-custom-realm-example[custom-realm-example]
|
|
||||||
repository on GitHub. You can use this code as a starting point for creating your
|
|
||||||
own realm.
|
|
||||||
|
|
||||||
To create a custom realm, you need to:
|
|
||||||
|
|
||||||
. Extend `org.elasticsearch.xpack.security.authc.Realm` to communicate with your
|
|
||||||
authentication system to authenticate users.
|
|
||||||
. Implement the `org.elasticsearch.xpack.security.authc.Realm.Factory` interface in
|
|
||||||
a class that will be used to create the custom realm.
|
|
||||||
. Extend `org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler` to
|
|
||||||
handle authentication failures when using your custom realm.
|
|
||||||
|
|
||||||
To package your custom realm as a plugin:
|
|
||||||
|
|
||||||
. Implement an extension class for your realm that extends
|
|
||||||
`org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to
|
|
||||||
override one or more of the following methods:
|
|
||||||
+
|
|
||||||
[source,java]
|
|
||||||
----------------------------------------------------
|
|
||||||
@Override
|
|
||||||
public Map<String, Factory> getRealms() {
|
|
||||||
...
|
|
||||||
}
|
|
||||||
----------------------------------------------------
|
|
||||||
+
|
|
||||||
The `getRealms` method is used to provide a map of type names to the `Factory` that
|
|
||||||
will be used to create the realm.
|
|
||||||
+
|
|
||||||
[source,java]
|
|
||||||
----------------------------------------------------
|
|
||||||
@Override
|
|
||||||
public AuthenticationFailureHandler getAuthenticationFailureHandler() {
|
|
||||||
...
|
|
||||||
}
|
|
||||||
----------------------------------------------------
|
|
||||||
+
|
|
||||||
The `getAuthenticationFailureHandler` method is used to optionally provide a
|
|
||||||
custom `AuthenticationFailureHandler`, which will control how {security} responds
|
|
||||||
in certain authentication failure events.
|
|
||||||
+
|
|
||||||
[source,java]
|
|
||||||
----------------------------------------------------
|
|
||||||
@Override
|
|
||||||
public List<String> getSettingsFilter() {
|
|
||||||
...
|
|
||||||
}
|
|
||||||
----------------------------------------------------
|
|
||||||
+
|
|
||||||
The `Plugin#getSettingsFilter` method returns a list of setting names that should be
|
|
||||||
filtered from the settings APIs as they may contain sensitive credentials. Note this method is not
|
|
||||||
part of the `SecurityExtension` interface, it's available as part of the elasticsearch plugin main class.
|
|
||||||
|
|
||||||
. Create a build configuration file for the plugin; Gradle is our recommendation.
|
|
||||||
. Create a `META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension` descriptor file for the
|
|
||||||
extension that contains the fully qualified class name of your `org.elasticsearch.xpack.core.security.SecurityExtension` implementation
|
|
||||||
. Bundle all in a single zip file.
|
|
||||||
|
|
||||||
[[using-custom-realm]]
|
|
||||||
==== Using a custom realm to authenticate users
|
|
||||||
|
|
||||||
To use a custom realm:
|
|
||||||
|
|
||||||
. Install the realm extension on each node in the cluster. You run
|
|
||||||
`bin/elasticsearch-plugin` with the `install` sub-command and specify the URL
|
|
||||||
pointing to the zip file that contains the extension. For example:
|
|
||||||
+
|
|
||||||
[source,shell]
|
|
||||||
----------------------------------------
|
|
||||||
bin/elasticsearch-plugin install file:///<path>/my-realm-1.0.zip
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
. Add a realm configuration of the appropriate realm type to `elasticsearch.yml`
|
|
||||||
under the `xpack.security.authc.realms` namespace. The options you can set depend
|
|
||||||
on the settings exposed by the custom realm. At a minimum, you must set the realm
|
|
||||||
`type` to the type defined by the extension. If you are configuring multiple
|
|
||||||
realms, you should also explicitly set the `order` attribute to control the
|
|
||||||
order in which the realms are consulted during authentication. You should make
|
|
||||||
sure each configured realm has a distinct `order` setting. In the event that
|
|
||||||
two or more realms have the same `order`, they will be processed in realm `name` order.
|
|
||||||
+
|
|
||||||
IMPORTANT: When you configure realms in `elasticsearch.yml`, only 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.
|
|
||||||
|
|
||||||
. Restart Elasticsearch.
|
|
||||||
|
|
@ -1,27 +0,0 @@
|
||||||
[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].
|
|
||||||
|
|
@ -1,13 +0,0 @@
|
||||||
[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>>.
|
|
||||||
|
|
@ -1,86 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[ldap-realm]]
|
|
||||||
=== LDAP user authentication
|
|
||||||
|
|
||||||
You can configure {security} to communicate with a Lightweight Directory Access
|
|
||||||
Protocol (LDAP) server to authenticate users. To integrate with LDAP, you
|
|
||||||
configure an `ldap` realm and map LDAP groups to user roles in the
|
|
||||||
<<mapping-roles, role mapping file>>.
|
|
||||||
|
|
||||||
LDAP stores users and groups hierarchically, similar to the way folders are
|
|
||||||
grouped in a file system. An LDAP 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).
|
|
||||||
|
|
||||||
The `ldap` realm supports two modes of operation, a user search mode
|
|
||||||
and a mode with specific templates for user DNs.
|
|
||||||
|
|
||||||
[[ldap-user-search]]
|
|
||||||
==== User search mode and user DN templates mode
|
|
||||||
|
|
||||||
See {ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
|
|
||||||
|
|
||||||
[[ldap-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 LDAP servers. {security} supports both
|
|
||||||
failover and load balancing modes of operation.
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
|
|
||||||
|
|
||||||
[[ldap-settings]]
|
|
||||||
==== LDAP realm settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].
|
|
||||||
|
|
||||||
[[mapping-roles-ldap]]
|
|
||||||
==== Mapping LDAP groups to roles
|
|
||||||
|
|
||||||
An integral part of a realm authentication process is to resolve the roles
|
|
||||||
associated with the authenticated user. Roles define the privileges a user has
|
|
||||||
in the cluster.
|
|
||||||
|
|
||||||
Since with the `ldap` realm the users are managed externally in the LDAP server,
|
|
||||||
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 users to to roles via their LDAP
|
|
||||||
groups, or other metadata. This role mapping can be 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 with LDAP, the privileges
|
|
||||||
for that user are the union of all privileges defined by the roles to which
|
|
||||||
the user is mapped. For more information, see
|
|
||||||
{ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
|
|
||||||
|
|
||||||
[[ldap-user-metadata]]
|
|
||||||
==== User metadata in LDAP realms
|
|
||||||
When a user is authenticated via an LDAP 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 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>>.
|
|
||||||
|
|
||||||
[[ldap-ssl]]
|
|
||||||
==== Setting up SSL Between Elasticsearch and LDAP
|
|
||||||
|
|
||||||
See {ref}/configuring-tls.html#tls-ldap[Encrypting Communications Between {es} and LDAP].
|
|
||||||
|
|
@ -1,31 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[native-realm]]
|
|
||||||
=== Native user authentication
|
|
||||||
|
|
||||||
The easiest way to manage and authenticate users is with the internal `native`
|
|
||||||
realm. You can use the REST APIs or Kibana to add and remove users, assign user roles, and
|
|
||||||
manage user passwords.
|
|
||||||
|
|
||||||
[[native-realm-configuration]]
|
|
||||||
[float]
|
|
||||||
==== Configuring a native realm
|
|
||||||
|
|
||||||
See {ref}/configuring-native-realm.html[Configuring a native realm].
|
|
||||||
|
|
||||||
[[native-settings]]
|
|
||||||
==== Native realm settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-native-settings[Native realm settings].
|
|
||||||
|
|
||||||
[[managing-native-users]]
|
|
||||||
==== Managing native users
|
|
||||||
|
|
||||||
{security} enables you to easily manage users in {kib} on the
|
|
||||||
*Management / Security / Users* page.
|
|
||||||
|
|
||||||
Alternatively, you can manage users through the `user` API. For more
|
|
||||||
information and examples, see {ref}/security-api-users.html[User management APIs].
|
|
||||||
|
|
||||||
[[migrating-from-file]]
|
|
||||||
NOTE: To migrate file-based users to the `native` realm, use the
|
|
||||||
{ref}/migrate-tool.html[migrate tool].
|
|
||||||
|
|
@ -1,64 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[setting-up-authentication]]
|
|
||||||
== User authentication
|
|
||||||
|
|
||||||
Authentication identifies an individual. To gain access to restricted resources,
|
|
||||||
a user must prove their identity, via passwords, credentials, or some other
|
|
||||||
means (typically referred to as authentication tokens).
|
|
||||||
|
|
||||||
The {stack} authenticates users by identifying the users behind the requests
|
|
||||||
that hit the cluster and verifying that they are who they claim to be. The
|
|
||||||
authentication process is handled by one or more authentication services called
|
|
||||||
<<realms,_realms_>>.
|
|
||||||
|
|
||||||
You can use the native support for managing and authenticating users, or
|
|
||||||
integrate with external user management systems such as LDAP and Active
|
|
||||||
Directory.
|
|
||||||
|
|
||||||
{security} provides built-in realms such as `native`,`ldap`, `active_directory`,
|
|
||||||
`pki`, `file`, and `saml`. If none of the built-in realms meet your needs, you
|
|
||||||
can also build your own custom realm and plug it into the {stack}.
|
|
||||||
|
|
||||||
When {security} is enabled, depending on the realms you've configured, you must
|
|
||||||
attach your user credentials to the requests sent to {es}. For example, when
|
|
||||||
using realms that support usernames and passwords you can simply attach
|
|
||||||
{wikipedia}/Basic_access_authentication[basic auth] header to the requests.
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/built-in-users.asciidoc
|
|
||||||
include::built-in-users.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/internal-users.asciidoc
|
|
||||||
include::internal-users.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/realms.asciidoc
|
|
||||||
include::realms.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc
|
|
||||||
include::active-directory-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/file-realm.asciidoc
|
|
||||||
include::file-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/ldap-realm.asciidoc
|
|
||||||
include::ldap-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/native-realm.asciidoc
|
|
||||||
include::native-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/pki-realm.asciidoc
|
|
||||||
include::pki-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/saml-realm.asciidoc
|
|
||||||
include::saml-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/custom-realm.asciidoc
|
|
||||||
include::custom-realm.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/anonymous-access.asciidoc
|
|
||||||
include::anonymous-access.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/user-cache.asciidoc
|
|
||||||
include::user-cache.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/saml-guide.asciidoc
|
|
||||||
include::saml-guide.asciidoc[]
|
|
||||||
|
|
@ -1,21 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[pki-realm]]
|
|
||||||
=== PKI user authentication
|
|
||||||
|
|
||||||
You can configure {security} to use Public Key Infrastructure (PKI) certificates
|
|
||||||
to authenticate users in {es}. This requires clients to present X.509
|
|
||||||
certificates.
|
|
||||||
|
|
||||||
NOTE: You cannot use PKI certificates to authenticate users in {kib}.
|
|
||||||
|
|
||||||
To use PKI in {es}, you configure a PKI realm, enable client authentication on
|
|
||||||
the desired network layers (transport or http), and map the Distinguished Names
|
|
||||||
(DNs) from the user certificates to {security} roles in the
|
|
||||||
<<mapping-roles, role mapping file>>.
|
|
||||||
|
|
||||||
See {ref}/configuring-pki-realm.html[Configuring a PKI realm].
|
|
||||||
|
|
||||||
[[pki-settings]]
|
|
||||||
==== PKI realm settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-pki-settings[PKI realm settings].
|
|
||||||
|
|
@ -1,124 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[realms]]
|
|
||||||
=== Realms
|
|
||||||
|
|
||||||
Authentication in {security} is handled by one or more authentication services
|
|
||||||
called _realms_. A _realm_ is used to resolve and authenticate users based on
|
|
||||||
authentication tokens. {security} provides the following built-in realms:
|
|
||||||
|
|
||||||
_native_::
|
|
||||||
An internal realm where users are stored in a dedicated {es} index.
|
|
||||||
This realm supports an authentication token in the form of username and password,
|
|
||||||
and is available by default when no realms are explicitly configured. The users
|
|
||||||
are managed via the {ref}/security-api-users.html[User Management API]. See
|
|
||||||
<<native-realm>>.
|
|
||||||
|
|
||||||
_ldap_::
|
|
||||||
A realm that uses an external LDAP server to authenticate the
|
|
||||||
users. This realm supports an authentication token in the form of username and
|
|
||||||
password, and requires explicit configuration in order to be used. See
|
|
||||||
<<ldap-realm>>.
|
|
||||||
|
|
||||||
_active_directory_::
|
|
||||||
A realm that uses an external Active Directory Server to authenticate the
|
|
||||||
users. With this realm, users are authenticated by usernames and passwords.
|
|
||||||
See <<active-directory-realm>>.
|
|
||||||
|
|
||||||
_pki_::
|
|
||||||
A realm that authenticates users using Public Key Infrastructure (PKI). This
|
|
||||||
realm works in conjunction with SSL/TLS and identifies the users through the
|
|
||||||
Distinguished Name (DN) of the client's X.509 certificates. See <<pki-realm>>.
|
|
||||||
|
|
||||||
_file_::
|
|
||||||
An internal realm where users are defined in files stored on each node in the
|
|
||||||
{es} cluster. This realm supports an authentication token in the form
|
|
||||||
of username and password and is always available. See <<file-realm>>.
|
|
||||||
|
|
||||||
_saml_::
|
|
||||||
A realm that facilitates authentication using the SAML 2.0 Web SSO protocol.
|
|
||||||
This realm is designed to support authentication through {kib} and is not
|
|
||||||
intended for use in the REST API. See <<saml-realm>>.
|
|
||||||
|
|
||||||
{security} also supports custom realms. If you need to integrate with another
|
|
||||||
authentication system, you can build a custom realm plugin. For more information,
|
|
||||||
see <<custom-realms, Integrating with Other Authentication Systems>>.
|
|
||||||
|
|
||||||
Realms live within a _realm chain_. It is essentially a prioritized list of
|
|
||||||
configured realms (typically of various types). The order of the list determines
|
|
||||||
the order in which the realms will be consulted. You should make sure each
|
|
||||||
configured realm has a distinct `order` setting. In the event that two or more
|
|
||||||
realms have the same `order`, they will be processed in `name` order.
|
|
||||||
During the authentication process, {security} will consult and try to
|
|
||||||
authenticate the request one realm at a time.
|
|
||||||
Once one of the realms successfully authenticates the request, the authentication
|
|
||||||
is considered to be successful and the authenticated user will be associated
|
|
||||||
with the request (which will then proceed to the authorization phase). If a realm
|
|
||||||
cannot authenticate the request, the next in line realm in the chain will be
|
|
||||||
consulted. If all realms in the chain could not authenticate the request, the
|
|
||||||
authentication is then considered to be unsuccessful and an authentication error
|
|
||||||
will be returned (as HTTP status code `401`).
|
|
||||||
|
|
||||||
NOTE: Some systems (e.g. Active Directory) have a temporary lock-out period after
|
|
||||||
several successive failed login attempts. If the same username exists in
|
|
||||||
multiple realms, unintentional account lockouts are possible. For more
|
|
||||||
information, please see <<trouble-shoot-active-directory, here>>.
|
|
||||||
|
|
||||||
The default realm chain contains the `native` and `file` realms. To explicitly,
|
|
||||||
configure a realm chain, you specify the chain in `elasticsearch.yml`. When you
|
|
||||||
configure a realm chain, only the realms you specify are used for authentication.
|
|
||||||
To use the `native` and `file` realms, you must include them in the chain.
|
|
||||||
|
|
||||||
The following snippet configures a realm chain that includes the `file` and
|
|
||||||
`native` realms, as well as two LDAP realms and an Active Directory realm.
|
|
||||||
|
|
||||||
[source,yaml]
|
|
||||||
----------------------------------------
|
|
||||||
xpack.security.authc:
|
|
||||||
realms:
|
|
||||||
|
|
||||||
file:
|
|
||||||
type: file
|
|
||||||
order: 0
|
|
||||||
|
|
||||||
native:
|
|
||||||
type: native
|
|
||||||
order: 1
|
|
||||||
|
|
||||||
ldap1:
|
|
||||||
type: ldap
|
|
||||||
order: 2
|
|
||||||
enabled: false
|
|
||||||
url: 'url_to_ldap1'
|
|
||||||
...
|
|
||||||
|
|
||||||
ldap2:
|
|
||||||
type: ldap
|
|
||||||
order: 3
|
|
||||||
url: 'url_to_ldap2'
|
|
||||||
...
|
|
||||||
|
|
||||||
ad1:
|
|
||||||
type: active_directory
|
|
||||||
order: 4
|
|
||||||
url: 'url_to_ad'
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
As can be seen above, each realm has a unique name that identifies it and each
|
|
||||||
realm type dictates its own set of required and optional settings. That said,
|
|
||||||
there are
|
|
||||||
{ref}/security-settings.html#ref-realm-settings[settings that are common to all realms].
|
|
||||||
|
|
||||||
Realm types can roughly be classified in two categories:
|
|
||||||
|
|
||||||
Internal:: Realms that are internal to Elasticsearch and don't require any
|
|
||||||
communication with external parties. They are fully managed by
|
|
||||||
{security}. There can only be a maximum of one configured realm
|
|
||||||
per internal realm type. {security} provides two internal realm
|
|
||||||
types: `native` and `file`.
|
|
||||||
|
|
||||||
External:: Realms that require interaction with parties/components external to
|
|
||||||
{es}, typically, with enterprise grade identity management
|
|
||||||
systems. Unlike internal realms, there can be as many external realms
|
|
||||||
as one would like - each with its own unique name and configuration.
|
|
||||||
{security} provides the following external realm types: `ldap`,
|
|
||||||
`active_directory`, `saml`, and `pki`.
|
|
||||||
|
|
@ -1,41 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[saml-realm]]
|
|
||||||
=== SAML authentication
|
|
||||||
{security} supports user authentication using SAML Single Sign On.
|
|
||||||
{security} provides this support using the Web Browser SSO profile of the SAML
|
|
||||||
2.0 protocol.
|
|
||||||
|
|
||||||
This protocol is specifically designed to support authentication via an
|
|
||||||
interactive web browser, so it does not operate as a standard authentication
|
|
||||||
realm. Instead, {security} provides features in {kib} and {es} that work
|
|
||||||
together to enable interactive SAML sessions.
|
|
||||||
|
|
||||||
This means that the SAML realm is not suitable for use by standard REST clients.
|
|
||||||
If you configure a SAML realm for use in {kib}, you should also configure
|
|
||||||
another realm, such as the <<native-realm, native realm>> in your authentication
|
|
||||||
chain.
|
|
||||||
|
|
||||||
In order to simplify the process of configuring SAML authentication within the
|
|
||||||
Elastic Stack, there is a step-by-step guide to
|
|
||||||
<<saml-guide, Configuring Elasticsearch and Kibana to use SAML Single-Sign-On>>.
|
|
||||||
|
|
||||||
The remainder of this document will describe {es} specific configuration options
|
|
||||||
for SAML realms.
|
|
||||||
|
|
||||||
[[saml-settings]]
|
|
||||||
==== SAML realm settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-saml-settings[SAML Realm Settings].
|
|
||||||
|
|
||||||
==== SAML realm signing settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-saml-signing-settings[SAML Realm Signing Settings].
|
|
||||||
|
|
||||||
==== SAML realm encryption settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-saml-encryption-settings[SAML Realm Encryption Settings].
|
|
||||||
|
|
||||||
==== SAML realm SSL settings
|
|
||||||
|
|
||||||
See {ref}/security-settings.html#ref-saml-ssl-settings[SAML Realm SSL Settings].
|
|
||||||
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[security-getting-started]]
|
|
||||||
== Getting started with security
|
|
||||||
|
|
||||||
To secure a cluster, you must enable {security} on every node in the
|
|
||||||
cluster. Basic authentication is enabled by default--to communicate
|
|
||||||
with the cluster, you must specify a username and password.
|
|
||||||
Unless you {xpack-ref}/anonymous-access.html[enable anonymous access], all
|
|
||||||
requests that don't include a user name and password are rejected.
|
|
||||||
|
|
||||||
To get started with {security}:
|
|
||||||
|
|
||||||
. {ref}/configuring-security.html[Configure security in {es}]. Encrypt
|
|
||||||
inter-node communications, set passwords for the
|
|
||||||
<<built-in-users,built-in users>>, and manage your users and roles.
|
|
||||||
|
|
||||||
. {kibana-ref}/using-kibana-with-security.html[Configure security in {kib}].
|
|
||||||
Set the authentication credentials in {kib} and encrypt communications between
|
|
||||||
the browser and the {kib} server.
|
|
||||||
|
|
||||||
. {logstash-ref}/ls-security.html[Configure security in Logstash]. Set the
|
|
||||||
authentication credentials for Logstash and encrypt communications between
|
|
||||||
Logstash and {es}.
|
|
||||||
|
|
||||||
. <<beats,Configure security in the Beats>>. Configure authentication
|
|
||||||
credentials and encrypt connections to {es}.
|
|
||||||
|
|
||||||
. Configure the Java transport client to use encrypted communications.
|
|
||||||
See <<java-clients>>.
|
|
||||||
|
|
||||||
. Configure {es} for Apache Hadoop to use secured transport. See
|
|
||||||
{hadoop-ref}/security.html[{es} for Apache Hadoop Security].
|
|
||||||
|
|
||||||
Depending on your security requirements, you might also want to:
|
|
||||||
|
|
||||||
* Integrate with {xpack-ref}/ldap-realm.html[LDAP] or {xpack-ref}/active-directory-realm.html[Active Directory],
|
|
||||||
or {xpack-ref}/pki-realm.html[require certificates] for authentication.
|
|
||||||
* Use {xpack-ref}/ip-filtering.html[IP Filtering] to allow or deny requests from particular
|
|
||||||
IP addresses or address ranges.
|
|
||||||
|
|
@ -1,100 +0,0 @@
|
||||||
[[xpack-security]]
|
|
||||||
= Securing Elasticsearch and Kibana
|
|
||||||
|
|
||||||
[partintro]
|
|
||||||
--
|
|
||||||
{security} enables you to easily secure a cluster. With Security,
|
|
||||||
you can password-protect your data as well as implement more advanced security
|
|
||||||
measures such as encrypting communications, role-based access control,
|
|
||||||
IP filtering, and auditing. This guide describes how to configure the security
|
|
||||||
features you need, and interact with your secured cluster.
|
|
||||||
|
|
||||||
Security protects Elasticsearch clusters by:
|
|
||||||
|
|
||||||
* <<preventing-unauthorized-access, Preventing unauthorized access>>
|
|
||||||
with password protection, role-based access control, and IP filtering.
|
|
||||||
* <<preserving-data-integrity, Preserving the integrity of your data>>
|
|
||||||
with message authentication and SSL/TLS encryption.
|
|
||||||
* <<maintaining-audit-trail, Maintaining an audit trail>>
|
|
||||||
so you know who's doing what to your cluster and the data it stores.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[preventing-unauthorized-access]]
|
|
||||||
=== Preventing Unauthorized Access
|
|
||||||
|
|
||||||
To prevent unauthorized access to your Elasticsearch cluster, you must have a
|
|
||||||
way to _authenticate_ users. This simply means that you need a way to validate
|
|
||||||
that a user is who they claim to be. For example, you have to make sure only
|
|
||||||
the person named _Kelsey Andorra_ can sign in as the user `kandorra`. {security}
|
|
||||||
provides a standalone authentication mechanism that enables you to
|
|
||||||
quickly password-protect your cluster. If you're already using {xpack-ref}/ldap-realm.html[LDAP],
|
|
||||||
{xpack-ref}/active-directory-realm.html[ Active Directory], or {xpack-ref}/pki-realm.html[ PKI] to manage
|
|
||||||
users in your organization, {security} is able to integrate with those
|
|
||||||
systems to perform user authentication.
|
|
||||||
|
|
||||||
In many cases, simply authenticating users isn't enough. You also need a way to
|
|
||||||
control what data users have access to and what tasks they can perform. {security}
|
|
||||||
enables you to _authorize_ users by assigning access _privileges_ to _roles_,
|
|
||||||
and assigning those roles to users. For example, this
|
|
||||||
{xpack-ref}/authorization.html[role-based access control] mechanism (a.k.a RBAC) enables
|
|
||||||
you to specify that the user `kandorra` can only perform read operations on the
|
|
||||||
`events` index and can't do anything at all with other indices.
|
|
||||||
|
|
||||||
{security} also supports {xpack-ref}/ip-filtering.html[ IP-based authorization]. You can
|
|
||||||
whitelist and blacklist specific IP addresses or subnets to control network-level
|
|
||||||
access to a server.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[preserving-data-integrity]]
|
|
||||||
=== Preserving Data Integrity
|
|
||||||
|
|
||||||
A critical part of security is keeping confidential data confidential.
|
|
||||||
Elasticsearch has built-in protections against accidental data loss and
|
|
||||||
corruption. However, there's nothing to stop deliberate tampering or data
|
|
||||||
interception. {security} preserves the integrity of your data by
|
|
||||||
{xpack-ref}/ssl-tls.html[encrypting communications] to and from nodes and
|
|
||||||
{xpack-ref}/enable-message-authentication.html[authenticating message] to verify that they
|
|
||||||
have not been tampered with or corrupted in transit during node-to-node
|
|
||||||
communication. For even greater protection, you can increase the
|
|
||||||
{xpack-ref}/ciphers.html[encryption strength] and
|
|
||||||
{xpack-ref}/separating-node-client-traffic.html[separate client traffic from node-to-node communications].
|
|
||||||
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[maintaining-audit-trail]]
|
|
||||||
=== Maintaining an Audit Trail
|
|
||||||
|
|
||||||
Keeping a system secure takes vigilance. By using {security} to maintain
|
|
||||||
an audit trail, you can easily see who is accessing your cluster and what they're
|
|
||||||
doing. By analyzing access patterns and failed attempts to access your cluster,
|
|
||||||
you can gain insights into attempted attacks and data breaches. Keeping an
|
|
||||||
auditable log of the activity in your cluster can also help diagnose operational
|
|
||||||
issues.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Where to Go Next
|
|
||||||
|
|
||||||
* <<security-getting-started, Getting Started>>
|
|
||||||
steps through how to install and start using Security for basic authentication.
|
|
||||||
|
|
||||||
* {xpack-ref}/how-security-works.html[How Security Works]
|
|
||||||
provides more information about how Security supports user authentication,
|
|
||||||
authorization, and encryption.
|
|
||||||
|
|
||||||
* {xpack-ref}/ccs-clients-integrations.html[Integrations]
|
|
||||||
shows you how to interact with an Elasticsearch cluster protected by
|
|
||||||
{security}.
|
|
||||||
|
|
||||||
* {xpack-ref}/security-reference.html[Reference]
|
|
||||||
provides detailed information about the access privileges you can grant to
|
|
||||||
users, the settings you can configure for Security in `elasticsearch.yml`,
|
|
||||||
and the files where Security configuration information is stored.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Have Comments, Questions, or Feedback?
|
|
||||||
|
|
||||||
Head over to our {security-forum}[Security Discussion Forum]
|
|
||||||
to share your experience, questions, and suggestions.
|
|
||||||
--
|
|
||||||
|
|
||||||
include::getting-started.asciidoc[]
|
|
||||||
|
|
@ -1,98 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[how-security-works]]
|
|
||||||
== How security works
|
|
||||||
|
|
||||||
An Elasticsearch cluster is typically made out of many moving parts. There are
|
|
||||||
the Elasticsearch nodes that form the cluster, and often Logstash instances,
|
|
||||||
Kibana instances, Beats agents an clients, all communicating with the it.
|
|
||||||
It should not come as a surprise that securing such clusters has many facets and
|
|
||||||
layers.
|
|
||||||
|
|
||||||
{security} provides the means to secure the Elastic cluster on several levels:
|
|
||||||
|
|
||||||
* <<setting-up-authentication>>
|
|
||||||
* Authorization and Role Based Access Control (a.k.a RBAC)
|
|
||||||
* Node/Client Authentication and Channel Encryption
|
|
||||||
* Auditing
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Authorization
|
|
||||||
|
|
||||||
The authorization process takes place once a request is authenticated and the
|
|
||||||
User behind the request is identified. Authorization is the process of determining
|
|
||||||
whether the user behind an incoming request is allowed to execute it. Naturally,
|
|
||||||
this process takes place right after an successful authentication - when the
|
|
||||||
user identity is known.
|
|
||||||
|
|
||||||
The authorization process revolves around the following 5 constructs:
|
|
||||||
|
|
||||||
_Secured Resource_::
|
|
||||||
A resource to which access is restricted. Indices/aliases, documents, fields,
|
|
||||||
users and the Elasticsearch cluster itself are all examples of secured objects.
|
|
||||||
|
|
||||||
_Privilege_::
|
|
||||||
A named group representing one or more actions that a user may execute against a
|
|
||||||
secured resource. Each secured resource has its own sets of available privileges.
|
|
||||||
For example, `read` is an index privilege that represents all actions that enable
|
|
||||||
reading the indexed/stored data. For a complete list of available privileges
|
|
||||||
see <<security-privileges>>.
|
|
||||||
|
|
||||||
_Permissions_::
|
|
||||||
A set of one or more privileges against a secured resource. Permissions can
|
|
||||||
easily be described in words, here are few examples:
|
|
||||||
* `read` privilege on the `products` index
|
|
||||||
* `manage` privilege on the cluster
|
|
||||||
* `run_as` privilege on `john` user
|
|
||||||
* `read` privilege on documents that match query X
|
|
||||||
* `read` privilege on `credit_card` field
|
|
||||||
|
|
||||||
_Role_::
|
|
||||||
A named sets of permissions
|
|
||||||
|
|
||||||
_User_::
|
|
||||||
The authenticated user.
|
|
||||||
|
|
||||||
A secure Elasticsearch cluster manages the privileges of users through _roles_.
|
|
||||||
A role has a unique name and identifies a set of permissions that translate to
|
|
||||||
privileges on resources. A user can be associated with an arbitrary number of
|
|
||||||
roles. The total set of permissions that a user has is therefore defined by
|
|
||||||
union of the permissions in all its roles.
|
|
||||||
|
|
||||||
Roles can be assigned to users in a number of ways depending on the realms by
|
|
||||||
which the users are authenticated.
|
|
||||||
|
|
||||||
For more information on user authentication see <<authorization>>
|
|
||||||
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Node/client authentication and channel encryption
|
|
||||||
|
|
||||||
{security} supports configuring SSL/TLS for securing the communication channels
|
|
||||||
to, from and within the cluster. This support accounts for:
|
|
||||||
|
|
||||||
* Encryption of data transmitted over the wires
|
|
||||||
* Certificate based node authentication - preventing unauthorized nodes/clients
|
|
||||||
from establishing a connection with the cluster.
|
|
||||||
|
|
||||||
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
|
|
||||||
you can restrict the nodes and clients that can connect to the cluster based
|
|
||||||
on their IP addresses. The IP filters configuration provides whitelisting
|
|
||||||
and blacklisting of IPs, subnets and DNS domains.
|
|
||||||
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Auditing
|
|
||||||
When dealing with any secure system, it is critical to have a audit trail
|
|
||||||
mechanism set in place. Audit trails log various activities/events that occur in
|
|
||||||
the system, enabling you to analyze and back track past events when things go
|
|
||||||
wrong (e.g. security breach).
|
|
||||||
|
|
||||||
{security} provides such audit trail functionality for all nodes in the cluster.
|
|
||||||
You can configure the audit level which accounts for the type of events that are
|
|
||||||
logged. These events include failed authentication attempts, user access denied,
|
|
||||||
node connection denied, and more.
|
|
||||||
|
|
||||||
For more information on auditing see <<auditing>>.
|
|
||||||
|
|
@ -1,123 +0,0 @@
|
||||||
[role="xpack"]
|
|
||||||
[[xpack-security]]
|
|
||||||
= Securing the {stack}
|
|
||||||
|
|
||||||
[partintro]
|
|
||||||
--
|
|
||||||
{security} enables you to easily secure a cluster. With {security},
|
|
||||||
you can password-protect your data as well as implement more advanced security
|
|
||||||
measures such as encrypting communications, role-based access control,
|
|
||||||
IP filtering, and auditing. This guide describes how to configure the security
|
|
||||||
features you need, and interact with your secured cluster.
|
|
||||||
|
|
||||||
Security protects Elasticsearch clusters by:
|
|
||||||
|
|
||||||
* <<preventing-unauthorized-access, Preventing unauthorized access>>
|
|
||||||
with password protection, role-based access control, and IP filtering.
|
|
||||||
* <<preserving-data-integrity, Preserving the integrity of your data>>
|
|
||||||
with message authentication and SSL/TLS encryption.
|
|
||||||
* <<maintaining-audit-trail, Maintaining an audit trail>>
|
|
||||||
so you know who's doing what to your cluster and the data it stores.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[preventing-unauthorized-access]]
|
|
||||||
=== Preventing Unauthorized Access
|
|
||||||
|
|
||||||
To prevent unauthorized access to your Elasticsearch cluster, you must have a
|
|
||||||
way to _authenticate_ users. This simply means that you need a way to validate
|
|
||||||
that a user is who they claim to be. For example, you have to make sure only
|
|
||||||
the person named _Kelsey Andorra_ can sign in as the user `kandorra`. {security}
|
|
||||||
provides a standalone authentication mechanism that enables you to
|
|
||||||
quickly password-protect your cluster. If you're already using <<ldap-realm, LDAP>>,
|
|
||||||
<<active-directory-realm, Active Directory>>, or <<pki-realm, PKI>> to manage
|
|
||||||
users in your organization, {security} is able to integrate with those
|
|
||||||
systems to perform user authentication.
|
|
||||||
|
|
||||||
In many cases, simply authenticating users isn't enough. You also need a way to
|
|
||||||
control what data users have access to and what tasks they can perform. {security}
|
|
||||||
enables you to _authorize_ users by assigning access _privileges_ to _roles_,
|
|
||||||
and assigning those roles to users. For example, this
|
|
||||||
<<authorization,role-based access control>> mechanism (a.k.a RBAC) enables
|
|
||||||
you to specify that the user `kandorra` can only perform read operations on the
|
|
||||||
`events` index and can't do anything at all with other indices.
|
|
||||||
|
|
||||||
{security} also supports <<ip-filtering, IP-based authorization>>. You can
|
|
||||||
whitelist and blacklist specific IP addresses or subnets to control network-level
|
|
||||||
access to a server.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[preserving-data-integrity]]
|
|
||||||
=== Preserving Data Integrity
|
|
||||||
|
|
||||||
A critical part of security is keeping confidential data confidential.
|
|
||||||
Elasticsearch has built-in protections against accidental data loss and
|
|
||||||
corruption. However, there's nothing to stop deliberate tampering or data
|
|
||||||
interception. {security} preserves the integrity of your data by
|
|
||||||
<<ssl-tls, encrypting communications>> to and from nodes.
|
|
||||||
For even greater protection, you can increase the <<ciphers, encryption strength>> and
|
|
||||||
<<separating-node-client-traffic, separate client traffic from node-to-node communications>>.
|
|
||||||
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[maintaining-audit-trail]]
|
|
||||||
=== Maintaining an Audit Trail
|
|
||||||
|
|
||||||
Keeping a system secure takes vigilance. By using {security} to maintain
|
|
||||||
an audit trail, you can easily see who is accessing your cluster and what they're
|
|
||||||
doing. By analyzing access patterns and failed attempts to access your cluster,
|
|
||||||
you can gain insights into attempted attacks and data breaches. Keeping an
|
|
||||||
auditable log of the activity in your cluster can also help diagnose operational
|
|
||||||
issues.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Where to Go Next
|
|
||||||
|
|
||||||
* <<security-getting-started, Getting Started>>
|
|
||||||
steps through how to install and start using Security for basic authentication.
|
|
||||||
|
|
||||||
* <<how-security-works, How Security Works>>
|
|
||||||
provides more information about how Security supports user authentication,
|
|
||||||
authorization, and encryption.
|
|
||||||
|
|
||||||
* <<ccs-clients-integrations>>
|
|
||||||
shows you how to interact with an Elasticsearch cluster protected by
|
|
||||||
{security}.
|
|
||||||
|
|
||||||
* <<security-reference, Reference>>
|
|
||||||
provides detailed information about the access privileges you can grant to
|
|
||||||
users, the settings you can configure for Security in `elasticsearch.yml`,
|
|
||||||
and the files where Security configuration information is stored.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
=== Have Comments, Questions, or Feedback?
|
|
||||||
|
|
||||||
Head over to our {security-forum}[Security Discussion Forum]
|
|
||||||
to share your experience, questions, and suggestions.
|
|
||||||
--
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/getting-started.asciidoc
|
|
||||||
include::getting-started.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/how-security-works.asciidoc
|
|
||||||
include::how-security-works.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/overview.asciidoc
|
|
||||||
include::authentication/overview.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authorization/overview.asciidoc
|
|
||||||
include::authorization/overview.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing.asciidoc
|
|
||||||
include::auditing/index.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/securing-communications.asciidoc
|
|
||||||
include::securing-communications.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/using-ip-filtering.asciidoc
|
|
||||||
include::using-ip-filtering.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ccs-clients-integrations.asciidoc
|
|
||||||
include::ccs-clients-integrations.asciidoc[]
|
|
||||||
|
|
||||||
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/reference.asciidoc
|
|
||||||
include::reference.asciidoc[]
|
|
||||||
Loading…
Reference in New Issue