[[how-shield-works]]
== How Shield Works

Shield installs as a plugin into Elasticsearch. Once installed, the plugin intercepts inbound API calls in order to
enforce authentication and authorization. The plugin can also provide encryption using Secure Sockets Layer/Transport
Layer Security (SSL/TLS) for the network traffic to and from the Elasticsearch node. The plugin also uses the API
interception layer that enables authentication and authorization to provide audit logging capability.


[float]
=== User Authentication

Shield defines a known set of users in order to authenticate users that make requests. These sets of users are defined
with an abstraction called a _realm_. A realm is a user database configured for the use of the Shield plugin. The
supported realms are _esusers_ and _LDAP_.

In the  _esusers_ realm, users exist exclusively within the Elasticsearch cluster. With the _esusers_ realm, the
administrator manages users with <<esusers,tools provided by Elasticsearch>>, and all the user operations occur within
the Elasticsearch cluster. Users authenticate with a username and password pair.

In the _LDAP_ realm, the administrator manages users with the tools provided by the LDAP vendor. Elasticsearch
authenticates users by accessing the configured LDAP server. Users authenticate with a username and password pair. Shield
also enables mapping LDAP groups to roles in Shield (more on roles below).

Your application can be a user in a Shield realm. Elasticsearch Clients authenticate to the cluster by providing a
username and password pair (a.k.a _Authentication Token_) with each request. To learn more on how different clients
can authenticate, see <<configuring-clients-integrations, Configuring Clients and Integrations>>.


[float]
=== Authorization

Shield's data model for action authorization consists of these elements:

* _Secured Resource_,   a resource against which security permissions are defined, including the cluster, an index/alias,
                        or a set of indices/aliases in the cluster

* _Privilege_,          one or more actions that a user may execute against a secured resource. This includes named groups of
                        actions (e.g. _read_), or a set specific actions (e.g. indices:/data/read/percolate)

* _Permissions_,        one or more privileges against a secured resource (e.g. _read on the "products" index_)

* _Role_,               named sets of permissions

* _Users_,              entities which may be assigned zero or more roles, authorizing them to perform the actions on the secure
                        resources described in the union of their roles

A secure Elasticsearch cluster manages the privileges of users through <<roles, _roles_>>. A role has a unique name and identifies
a set of permissions that translate to privileges on resources. A user can have an arbitrary number of roles. There are
two types of permissions: _cluster_ and _index_. The total set of permissions that a user has is defined by union of the
permissions in all its roles.

Depending on the realm used, Shield provides the appropriate means to assign roles to users.


[float]
=== Node Authentication and Channel Encryption

Nodes communicate to other nodes over port 9300. With Shield, you can use SSL/TLS to wrap this communication. When
SSL/TLS is enabled, the nodes validate each other's certificates, establishing trust between the nodes. This validation
prevents unauthenticated nodes from joining the cluster. Communications between nodes in the cluster are also encrypted
when SSL/TLS is in use.

Users are responsible for generating and installing their own certificates.

You can choose a variety of ciphers for encryption. See the <<ciphers,_Adding Ciphers to Java for Stronger Encryption_>>
section for details.

For more information on how to secure nodes see <<securing-communications, Securing Communications with Encryption and IP Filtering>>.


[float]
=== IP Filtering
Shield provides IP-based access control for Elasticsearch nodes. This access control allows you to restrict which
other servers, via their IP address, can connect to your Elasticsearch nodes and make requests. For example, you can
configure Shield to allow access to the cluster only from your application servers. The configuration provides for
whitelisting and blacklisting of subnets, specific IP addresses, and DNS domains. To read more about IP filtering see
<<ip-filtering, IP filtering>>.


[float]
=== Auditing
The <<configuring-auditing,audit functionality>> in a secure Elasticsearch cluster logs particular events and activity on that
cluster. The events logged include authentication attempts, including granted and denied access.