elasticsearch/x-pack/docs/en/security/ccs-clients-integrations/java.asciidoc

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

deprecated[7.0.0, The `TransportClient` is deprecated in favour of the {java-rest}/java-rest-high.html[Java High Level REST Client] and will be removed in Elasticsearch 8.0. The {java-rest}/java-rest-high-level-migration.html[migration guide] describes all the steps needed to migrate.]

The {es} {security-features} support 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]]
. {ref}/setup-xpack-client.html[Configure the {xpack} transport client].

. Configure a user with the privileges required to start the transport client.
A default `transport_client` role is built-in to the {es} {security-features},
which 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.

. 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 TransportAddress("localhost", 9300))
    .addTransportAddress(new TransportAddress("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.TransportAddress;
import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;

import static 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 TransportAddress(InetAddress.getByName("localhost"), 9300))
    .addTransportAddress(new TransportAddress(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 TransportAddress(InetAddress.getByName("localhost"), 9300))
    .addTransportAddress(new TransportAddress(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 TransportAddress("localhost", 9300))
    .addTransportAddress(new TransportAddress("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

The {stack} {security-features} expose an API through the `SecurityClient` class.
To get a hold of a `SecurityClient` you first need to create the `XPackClient`,
which is a wrapper around the existing {es} clients (any client class implementing
`org.elasticsearch.client.Client`).

The following example shows how you can clear the 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.