Java clients

If you plan on using the Node Client, you first need to make sure the Shield jar files (elasticsearch-shield-1.2.3.jar, commons-codec-1.10.jar, automaton-1.11-8.jar, unboundid-ldapsdk-2.3.8.jar) and the License jar file (elasticsearch-license-1.0.0.jar) are in the classpath. You can either download the distributions, extract the jar files manually and include them in your classpath, or you can pull them out of the Elasticsearch Maven repository.

The following snippet shows the configuration you will need to include in your project’s pom.xml file:

<project ...>

   <repositories>
      <!-- add the elasticsearch repo -->
      <repository>
         <id>elasticsearch-releases</id>
         <url>http://maven.elasticsearch.org/releases</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>false</enabled>
         </snapshots>
      </repository>
      ...
   </repositories>
   ...

   <dependencies>
      <!-- add the Shield jar as a dependency -->
      <dependency>
         <groupId>org.elasticsearch</groupId>
         <artifactId>elasticsearch-shield</artifactId>
         <version>1.2.3</version>
      </dependency>
      <!-- add the License jar as a dependency -->
      <dependency>
         <groupId>org.elasticsearch</groupId>
         <artifactId>elasticsearch-license-plugin</artifactId>
         <version>1.0.0</version>
         <scope>runtime</scope>
      </dependency>
      ...
   </dependencies>
   ...

 </project>

If you are using Gradle, then you will need to add the dependencies to your build.gradle file:

repositories {
  /* ... Any other repositories ... */

  // Add the Elasticsearch Maven Repository
  maven {
    url "http://maven.elasticsearch.org/releases"
  }
}

dependencies {
  // Provide the Shield jar on the classpath for compilation and at runtime
  // Note: Many projects can use the Shield jar as a runtime dependency
  compile "org.elasticsearch:elasticsearch-shield:1.2.3"

  /* ... */

  // Provide the License jar on the classpath at runtime (not needed for compilation)
  runtime "org.elasticsearch:elasticsearch-license-plugin:1.0.0"
}

It is also possible to manually download the Shield jar and the License jar files from our Maven repository.

The Node Client will authenticate requests before sending the requests to the cluster. To do this, copy the users, users_roles, roles.yml, and system_key files from the Shield configuration files to a place accessible to the node client. These files should be stored on the filesystem in a folder with restricted access as they contain sesnitive data. This can be configured with the following settings:

import static org.elasticsearch.node.NodeBuilder.*;
...
Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
    .put("cluster.name", "myClusterName")
    .put("discovery.zen.ping.multicast.enabled", false)
    .putArray("discovery.zen.ping.unicast.hosts", "localhost:9300", "localhost:9301")
    .put("shield.authc.realms.esusers.type", "esusers")
    .put("shield.authc.realms.esusers.files.users", "/Users/es/config/shield/users")
    .put("shield.authc.realms.esusers.files.users_roles", "/Users/es/config/shield/users_roles")
    .put("shield.authz.store.files.roles", "/Users/es/config/shield/roles.yml")
    .put("shield.system_key.file", "/Users/es/config/shield/system_key"))
    ...
    .node();

Additionally, if you are using LDAP or Active Directory authentication then you will need to specify that configuration in the settings when configuring the node or provide a elasticsearch.yml in the classpath with the appropriate settings.

The authentication token can be configured in two ways - globally or per-request. When setting it up globally, the values of the username and password are configured in the client’s settings:

import static org.elasticsearch.node.NodeBuilder.*;
import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
...

Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
    ...
    .put("shield.user", "test_user:changeme"))
    ...
    .node();
Client client = node.client();

Once the client is created as above, the shield.user setting is translated to a request header in the standard HTTP basic authentication form Authentication base64("test_user:changeme") which will be sent with every request executed.

To skip the global configuration of the token, manually set the authentication token header on every request:

import org.elasticsearch.shield.authc.support.SecuredString;

import static org.elasticsearch.node.NodeBuilder.*;
import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
...

String token = basicAuthHeaderValue("test_user", new SecuredString("changeme".toCharArray()));
Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
    ...
    .node();
Client client = node.client();

client.prepareSearch().putHeader("Authorization", token).get();

The example above executes a search request and manually adds the authentication token as a header on it.

Authenticating to the cluster requires proof that a node client is trusted as part of the cluster. This is done through standard PKI and SSL. A client node creates a private key and an associated certificate. The cluster Certificate Authority signs the certificate. A Client node authenticates during the SSL connection setup by presenting the signed certificate, and proving ownership of the private key. All of these setup steps are described in Securing Nodes.

In addition, the node client acts like a node, authenticating locally any request made. Copies of the files users, users_roles, roles.yml , and system_key need to be made available to the node client.

After following the steps in Securing Nodes, configuration for a node client with Shield might look like this:

import static org.elasticsearch.node.NodeBuilder.*;
...
Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
    .put("cluster.name", "myClusterName")
    .put("discovery.zen.ping.multicast.enabled", false)
    .putArray("discovery.zen.ping.unicast.hosts", "localhost:9300", "localhost:9301")
    .put("shield.ssl.keystore.path", "/Users/es/node_client/node_client.jks")
    .put("shield.ssl.keystore.password", "password")
    .put("shield.transport.ssl", "true")
    .put("shield.authc.realms.esusers.type", "esusers")
    .put("shield.authc.realms.esusers.files.users", "/Users/es/config/shield/users")
    .put("shield.authc.realms.esusers.files.users_roles", "/Users/es/config/shield/users_roles")
    .put("shield.authz.store.files.roles", "/Users/es/config/shield/roles.yml")
    .put("shield.system_key.file", "/Users/es/config/shield/system_key"))
    ...
    .node();

The following snippet shows the configuration you will need to include in your project’s pom.xml file:

<project ...>

   <repositories>
      <!-- add the elasticsearch repo -->
      <repository>
         <id>elasticsearch-releases</id>
         <url>http://maven.elasticsearch.org/releases</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>false</enabled>
         </snapshots>
      </repository>
      ...
   </repositories>
   ...

   <dependencies>
      <!-- add the shield jar as a dependency -->
      <dependency>
         <groupId>org.elasticsearch</groupId>
         <artifactId>elasticsearch-shield</artifactId>
         <version>1.2.3</version>
      </dependency>
      ...
   </dependencies>
   ...

 </project>

If you are using Gradle, then you will need to add the dependencies to your build.gradle file:

repositories {
  /* ... Any other repositories ... */

  // Add the Elasticsearch Maven Repository
  maven {
    url "http://maven.elasticsearch.org/releases"
  }
}

dependencies {
  // Provide the Shield jar on the classpath for compilation and at runtime
  // Note: Many projects can use the Shield jar as a runtime dependency
  compile "org.elasticsearch:elasticsearch-shield:1.2.3"

  /* ... */
}

It is also possible to manually download the Shield jar file from our Maven repository.

Before setting up the client itself, you need to make sure you have a user with sufficient privileges to start the transport client. The transport client uses Elasticsearch’s node info API to fetch information about the nodes in the cluster. For this reason, the authenticated user of the transport client must have the cluster:monitor/nodes/info cluster permission. Furthermore, if the client is configured to use sniffing, the cluster:monitor/state cluster permission is required.

Setting up the transport client is similar to the Node client except authentication files do not need to be configured. Without SSL, it is as easy as setting up the authentication token on the request, similarly to how they’re set up with the Node Client:

import org.elasticsearch.client.transport.TransportClient;
...

TransportClient client = new TransportClient(ImmutableSettings.builder()
    .put("cluster.name", "myClusterName")
    .put("shield.user", "test_user:changeme")
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));

When using SSL for transport client communication, a few more settings are required. By default, Shield requires client authentication for secured transport communication. This means that every client would need to have a certificate signed by a trusted CA. The client authentication can be disabled through the use of a client specific transport profile.

Configuration required for SSL when using client authentication:

import org.elasticsearch.client.transport.TransportClient;
...

TransportClient client = new TransportClient(ImmutableSettings.builder()
    .put("cluster.name", "myClusterName")
    .put("shield.user", "test_user:changeme")
    .put("shield.ssl.keystore.path", "/path/to/client.jks")
    .put("shield.ssl.keystore.password", "password")
    .put("shield.transport.ssl", "true"))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));

Configuration required for SSL without client authentication:

import org.elasticsearch.client.transport.TransportClient;
...

TransportClient client = new TransportClient(ImmutableSettings.builder()
    .put("cluster.name", "myClusterName")
    .put("shield.user", "test_user:changeme")
    .put("shield.ssl.truststore.path", "/path/to/truststore.jks")
    .put("shield.ssl.truststore.password", "password")
    .put("shield.transport.ssl", "true"))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));

In the above code snippets, we set up a Transport Client and configured the authentication token globally. Meaning, that every request executed with this client will include this token in its headers.

The global configuration of the token must be set to some user with the privileges in the default transport_client role, as described earlier. The global authentication token may also be overridden by adding a Authorization header on each request. This is useful when an application uses multiple users to access Elasticsearch via the same client. When operating in this mode, it is best to set the global token to a user that only has the transport_client role. The following example directly sets the authentication token on the request when executing a search.

import org.elasticsearch.shield.authc.support.SecuredString;
import org.elasticsearch.client.transport.TransportClient;

import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
...

String token = basicAuthHeaderValue("test_user", new SecuredString("changeme".toCharArray()));
TransportClient client = new TransportClient(ImmutableSettings.builder()
    .put("shield.user", "transport_client_user:changeme")
    ...
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));

client.prepareSearch().putHeader("Authorization", token).get();

If Shield enables anonymous access, the shield.user setting may be dropped and all requests will be executed under the anonymous user (with the exception of the requests on which the Authorization header is explicitly set, as shown above). For this to work, please make sure the anonymous user is configured with sufficient roles that have the same privileges as described above.