[[java-clients]]
=== Java Client and Security

{security} supports the Java http://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-client.html[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.

NOTE: Using the Java Node Client with secured clusters is not recommended or
      supported.

[float]
[[transport-client]]
==== Configuring the Transport Client to work with a Secured Cluster

To use the transport client with a secured cluster, you need to:

[[java-transport-client-role]]
. Configure a user with the privileges required to start the transport client.
A default `transport_client` role is built-in to {xpack} that grants the
appropriate cluster permissions for the transport client to work with the secured
cluster. The transport client uses the _Nodes Info API_ to fetch information about
the nodes in the cluster.

. Add the {xpack} transport JAR file to your CLASSPATH. You can download the {xpack}
distribution and extract the JAR file manually or you can get it from the
https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.jar[Elasticsearch Maven repository].
+
As with any dependency, you will also need its transitive dependencies. Refer to the
https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.pom[X-Pack POM file
for your version] when downloading for offline usage.
--

If you are using Maven, you need to add the {xpack} JAR file as a dependency in
your project's `pom.xml` file:

[source,xml]
--------------------------------------------------------------
<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 x-pack jar as a dependency -->
      <dependency>
         <groupId>org.elasticsearch.client</groupId>
         <artifactId>x-pack-transport</artifactId>
         <version>{version}</version>
      </dependency>
      ...
   </dependencies>
   ...

 </project>
--------------------------------------------------------------

If you are using Gradle, you need to add the {xpack} JAR file as a dependency in
your `build.gradle` file:

[source,groovy]
--------------------------------------------------------------
repositories {
  /* ... Any other repositories ... */

  // Add the Elasticsearch Maven Repository
  maven {
    url "https://artifacts.elastic.co/maven"
  }
}

dependencies {
  compile "org.elasticsearch.client:x-pack-transport:{version}"

  /* ... */
}
--------------------------------------------------------------
--

If you are using a repository manager such as https://www.sonatype.com/nexus-repository-oss[Nexus OSS] within your
company, you need to add the repository as per the following screenshot:


image::images/nexus.png["Adding the Elastic repo in Nexus",link="images/nexus.png"]


Then in your project's `pom.xml` if using maven, add the following repositories and dependencies definitions:

[source,xml]
--------------------------------------------------------------
<dependencies>
    <dependency>
        <groupId>org.elasticsearch.client</groupId>
        <artifactId>x-pack-transport</artifactId>
        <version>{version}</version>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>local-nexus</id>
        <name>Elastic Local Nexus</name>
        <url>http://0.0.0.0:8081/repository/elasticsearch/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>
--------------------------------------------------------------

. Set up the transport client. At a minimum, you must configure `xpack.security.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 the `transport_client_user` credentials in
its headers.
+
[source,java]
-------------------------------------------------------------------------------------------------
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
...

TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
        .put("cluster.name", "myClusterName")
        .put("xpack.security.user", "transport_client_user:x-pack-test-password")
        ...
        .build())
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
-------------------------------------------------------------------------------------------------
+
WARNING:  If you configure a transport client without SSL, passwords are sent in
          clear text.
+
You can also add an `Authorization` header to each request. If you've configured
global authorization credentials, the `Authorization` 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 the `transport_client` role, and add the `transport_client`
role to the individual users.
+
For example, the following snippet adds the `Authorization` header to a search
request:
+
[source,java]
--------------------------------------------------------------------------------------------------
import org.elasticsearch.common.settings.SecureString;
import org.elasticsearch.common.settings.Settings;
import org.elasticsearch.common.transport.InetSocketTransportAddress;
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;

import static org.elasticsearch.xpack.security.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
...

TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
        .put("cluster.name", "myClusterName")
        .put("xpack.security.user", "transport_client_user:x-pack-test-password")
        ...
        .build())
    .build()
    .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300))
    .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301))

String token = basicAuthHeaderValue("test_user", new SecureString("x-pack-test-password".toCharArray()));

client.filterWithHeader(Collections.singletonMap("Authorization", token))
    .prepareSearch().get();
--------------------------------------------------------------------------------------------------

. Enable SSL to authenticate clients and encrypt communications. To enable SSL,
you need to:

.. Configure the paths to the client's key and certificate in addition to the certificate authorities.
Client authentication requires every client to have a certification signed by a trusted CA.
+
NOTE: Client authentication is enabled by default. For information about
      disabling client authentication, see <<disabling-client-auth, Disabling Client Authentication>>.
+
[source,java]
--------------------------------------------------------------------------------------------------
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
...

TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
        .put("cluster.name", "myClusterName")
        .put("xpack.security.user", "transport_client_user:x-pack-test-password")
        .put("xpack.ssl.key", "/path/to/client.key")
        .put("xpack.ssl.certificate", "/path/to/client.crt")
        .put("xpack.ssl.certificate_authorities", "/path/to/ca.crt")
        ...
        .build());
--------------------------------------------------------------------------------------------------

+
.. Enable the SSL transport by setting `xpack.security.transport.ssl.enabled` to `true` in the
client configuration.
+
[source,java]
--------------------------------------------------------------------------------------------------
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
...

TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
        .put("cluster.name", "myClusterName")
        .put("xpack.security.user", "transport_client_user:x-pack-test-password")
        .put("xpack.ssl.key", "/path/to/client.key")
        .put("xpack.ssl.certificate", "/path/to/client.crt")
        .put("xpack.ssl.certificate_authorities", "/path/to/ca.crt")
        .put("xpack.security.transport.ssl.enabled", "true")
        ...
        .build())
    .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300))
    .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301))
--------------------------------------------------------------------------------------------------

[float]
[[disabling-client-auth]]
===== Disabling Client Authentication

If you want to disable client authentication, you can use a client-specific
transport protocol. For more information see <<separating-node-client-traffic, 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 provide the path to the CA
certificate in your client configuration.

[source,java]
------------------------------------------------------------------------------------------------------
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
...

TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
        .put("cluster.name", "myClusterName")
        .put("xpack.security.user", "test_user:x-pack-test-password")
        .put("xpack.ssl.certificate_authorities", "/path/to/ca.crt")
        .put("xpack.security.transport.ssl.enabled", "true")
        ...
        .build())
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
    .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
------------------------------------------------------------------------------------------------------

NOTE: If you are using a public CA that is already trusted by the Java runtime,
      you do not need to set the `xpack.ssl.certificate_authorities`.

[float]
[[connecting-anonymously]]
===== Connecting Anonymously

To enable the transport client to connect anonymously, you must assign the
anonymous user the privileges defined in the <<java-transport-client-role,transport_client>>
role. Anonymous access must also be enabled, of course. For more information,
see <<anonymous-access,Enabling Anonymous Access>>.

[float]
[[security-client]]
==== Security Client

{security} exposes its own API through the `SecurityClient` class. To get a hold
of a `SecurityClient` you'll first need to create the `XPackClient`, which is a
wrapper around the existing Elasticsearch clients (any client class implementing
`org.elasticsearch.client.Client`).

The following example shows how you can clear {security}'s realm caches using
the `SecurityClient`:

[source,java]
------------------------------------------------------------------------------------------------------
Client client = ... // create the transport client

XPackClient xpackClient = new XPackClient(client);
SecurityClient securityClient = xpackClient.security();
ClearRealmCacheResponse response = securityClient.authc().prepareClearRealmCache()
    .realms("ldap1", "ad1") <1>
    .usernames("rdeniro")
    .get();
------------------------------------------------------------------------------------------------------
<1> Clears the `ldap1` and `ad1` realm caches for the `rdeniro` user.