Architecture Overview

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.

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 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 Clients.

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. 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.

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.

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.

Auditing

The 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.