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.

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 native, file, LDAP, Active Directory, PKI.

In the native realm, users are stored and distributed with the Elasticsearch cluster. With the native realm, the administrator manages users with the API for user management, and all the user operations occur within the Elasticsearch cluster. Users authenticate with a username and password pair.

In the file realm, users exist in files stored on each node of the Elasticsearch cluster. With the file 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).

In the Active Directory realm, the administrator manages users within Active Directory. Elasticsearch authenticates users using the LDAP protocol to Active Directory. Users authenticate with a username and password pair. Shield also enables mapping Active Directory security groups to roles in Shield.

In the PKI realm, the administrator manages users with tools for X.509 certificate management. Elasticsearch authenticates users by validating that their X.509 certificate has been signed by a trusted authority. Users authenticate by presenting their PKI certificate during TLS communication and Shield maps the subject to the appropriate roles.

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

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

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.

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 Adding Ciphers to Java for Stronger Encryption section for details.

For more information on how to secure nodes see Securing Communications with Encryption and 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.

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.