Using Elasticsearch Java Clients with Shield
editUsing Elasticsearch Java Clients with Shield
editShield supports the Java transport client for Elasticsearch. The transport client uses the same transport protocol that the cluster nodes use for inter-node communication. It is very efficient as it does not have to marshall and unmarshall JSON requests like a typical REST client.
Using the Java Node Client with Shield is not recommended or supported.
Configuring the Transport Client to work with Shield
editTo use the transport client with Shield, you need to:
-
Configure a user with the privileges required to start the transport client. A default
transport_client
role is defined inroles.yml
that grants thetransport_client
cluster privilege. The transport client uses the node info API to fetch information about the nodes in the cluster. -
Add the Shield JAR file (
shield-2.2.0.jar
) to your CLASSPATH. You can download the Shield distribution and extract the JAR file manually or you can get it from the Elasticsearch Maven repository.If you are using Maven, you need to add the Shield JAR file as a dependency in your project’s
pom.xml
file:<project ...> <repositories> <!-- add the elasticsearch repo --> <repository> <id>elasticsearch-releases</id> <url>https://artifacts.elastic.co/maven</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.plugin</groupId> <artifactId>shield</artifactId> <version>2.2.0</version> </dependency> ... </dependencies> ... </project>
If you are using Gradle, you need to add the Shield JAR file as a dependency in your
build.gradle
file:repositories { /* ... Any other repositories ... */ // Add the Elasticsearch Maven Repository maven { url "https://artifacts.elastic.co/maven" } } 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.plugin:shield:2.2.0" /* ... */ }
-
Set up the transport client. At a minimum, you must configure
shield.user
to include the name and password of your transport client user in your requests. The following snippet configures the user credentials globally—every request submitted with this client includes thetransport_client_user
credentials in its headers.import org.elasticsearch.client.transport.TransportClient; import org.elasticsearch.shield.ShieldPlugin ... TransportClient client = TransportClient.builder() .addPlugin(ShieldPlugin.class) .settings(Settings.builder() .put("cluster.name", "myClusterName") .put("shield.user", "transport_client_user:changeme") ... .build()) .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
If you configure a transport client without SSL, passwords are sent in plaintext.
You can also add an
Authorization
header to each request. If you’ve configured global authorization credentials, theAuthorization
header overrides the global authentication credentials. This is useful when an application has multiple users who access Elasticsearch using the same client. You can set the global token to a user that only has thetransport_client
role, and add thetransport_client
role to the individual users.For example, the following snippet adds the
Authorization
header to a search request:import org.elasticsearch.client.transport.TransportClient; import org.elasticsearch.common.settings.Settings; import org.elasticsearch.common.transport.InetSocketTransportAddress; import org.elasticsearch.shield.authc.support.SecuredString; import org.elasticsearch.shield.ShieldPlugin import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue; ... TransportClient client = TransportClient.builder() .addPlugin(ShieldPlugin.class) .settings(Settings.builder() .put("cluster.name", "myClusterName") .put("shield.user", "transport_client_user:changeme") ... .build()) .build() .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300)) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301)) String token = basicAuthHeaderValue("test_user", new SecuredString("changeme".toCharArray())); client.prepareSearch().putHeader("Authorization", token).get();
-
Enable SSL to authenticate clients and encrypt communications. To enable SSL, you need to:
-
Configure the client’s keystore path and password. Client authentication requires every client to have a certification signed by a trusted CA.
Client authentication is enabled by default. For information about disabling client authentication, see Disabling Client Authentication.
import org.elasticsearch.client.transport.TransportClient; import org.elasticsearch.shield.ShieldPlugin ... TransportClient client = TransportClient.builder() .addPlugin(ShieldPlugin.class) .settings(Settings.builder() .put("cluster.name", "myClusterName") .put("shield.user", "transport_client_user:changeme") .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) .put("shield.ssl.keystore.password", "password") ... .build());
(1) The
client.jks
keystore must contain the client’s signed certificate and the CA certificate. -
Enable the SSL transport by setting
shield.transport.ssl
totrue
in the client configuration.import org.elasticsearch.client.transport.TransportClient; import org.elasticsearch.shield.ShieldPlugin ... TransportClient client = TransportClient.builder() .addPlugin(ShieldPlugin.class) .settings(Settings.builder() .put("cluster.name", "myClusterName") .put("shield.user", "transport_client_user:changeme") .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) .put("shield.ssl.keystore.password", "password") .put("shield.transport.ssl", "true") ... .build()) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300)) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301))
-
Disabling Client Authentication
editIf you want to disable client authentication, you can use a client-specific transport protocol. For more information, Separating Node to Node and Client Traffic.
If you are not using client authentication and sign the Elasticsearch node certificates with your own CA, you need to set the truststore path and password in the client configuration:
import org.elasticsearch.client.transport.TransportClient; import org.elasticsearch.shield.ShieldPlugin ... TransportClient client = TransportClient.builder() .addPlugin(ShieldPlugin.class) .settings(Settings.builder() .put("cluster.name", "myClusterName") .put("shield.user", "test_user:changeme") .put("shield.ssl.truststore.path", "/path/to/truststore.jks") (1) .put("shield.ssl.truststore.password", "password") .put("shield.transport.ssl", "true") ... .build()) .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
(1) The truststore.jks
truststore must contain the certificate of the CA that signed the Elasticsearch node certificates.
If you are using a public CA that is already trusted by the Java runtime, you to not need to set the shield.ssl.truststore.path
and shield.ssl.truststore.password
.
Connecting Anonymously [1.1.0] Added in 1.1.0.
editTo enable the transport client to connect anonymously, you must assign the anonymous user the privileges defined in the transport_client role. Anonymous access must also be enabled, of course. For more information, see Enabling Anonymous Access.
Shield Client
editShield exposes its own API through the ShieldClient
class. At the moment, this API only exposes one operation, for clearing the realm caches. ShieldClient
is a wrapper around the existing clients (any client class implementing org.elasticsearch.client.Client
).
The following example shows how you can clear Shield’s realm caches using ShieldClient
:
import static org.elasticsearch.node.NodeBuilder.*; ... Client client = ... // create the transport client ShieldClient shieldClient = new ShieldClient(client); ClearRealmCacheResponse response = shieldClient.authc().prepareClearRealmCache() .realms("ldap1", "ad1") (1) .usernames("rdeniro") .get();
(1) Clears the ldap1
and ad1
realm caches for the rdeniro
user.