[[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.] {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]] . {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 {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. . 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 <>. [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 <>. 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 <> role. Anonymous access must also be enabled, of course. For more information, see <>. [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.