- X-Pack Reference for 6.0-6.2 and 5.x:
- Introduction
- Setting Up X-Pack
- Breaking Changes
- X-Pack APIs
- Graphing Connections in Your Data
- Profiling your Queries and Aggregations
- Reporting from Kibana
- Securing the Elastic Stack
- Getting Started with Security
- How Security Works
- Setting Up User Authentication
- Configuring SAML Single-Sign-On on the Elastic Stack
- Configuring Role-based Access Control
- Auditing Security Events
- Encrypting Communications
- Restricting Connections with IP Filtering
- Cross Cluster Search, Tribe, Clients and Integrations
- Reference
- Monitoring the Elastic Stack
- Alerting on Cluster and Index Events
- Machine Learning in the Elastic Stack
- Troubleshooting
- Getting Help
- X-Pack security
- Can’t log in after upgrading to 6.2.4
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- X-Pack Watcher
- X-Pack monitoring
- X-Pack machine learning
- Limitations
- License Management
- Release Notes
WARNING: Version 6.2 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Java Client and Security
editJava Client and Security
editX-Pack security 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 secured clusters is not recommended or supported.
Configuring the Transport Client to work with a Secured Cluster
editWe plan on deprecating the TransportClient
in Elasticsearch 7.0 and removing
it completely in 8.0. Instead, you should be using the
Java High Level REST Client, which executes
HTTP requests rather than serialized Java requests. The
migration guide describes
all the steps needed to migrate.
The Java High Level REST Client currently has support for the more commonly used APIs, but there are a lot more that still need to be added. You can help us prioritise by telling us which missing APIs you need for your application by adding a comment to this issue: Java high-level REST client completeness.
Any missing APIs can always be implemented today by using the low level Java REST Client with JSON request and response bodies.
To use the transport client with a secured cluster, you need to:
- Configure the X-Pack transport client.
-
Configure a user with the privileges required to start the transport client.
A default
transport_client
role is built-in to X-Pack 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 thetransport_client_user
credentials in its headers.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));
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, 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.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.
Client authentication is enabled by default. For information about disabling client authentication, see Disabling Client Authentication.
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
totrue
in the client configuration.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))
-
Disabling Client Authentication
editIf you want to disable client authentication, you can use a client-specific transport protocol. For more information see 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.
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));
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
.
Connecting Anonymously
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.
Security Client
editX-Pack 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 X-Pack security’s realm caches using
the SecurityClient
:
On this page
ElasticON events are back!
Learn about the Elastic Search AI Platform from the experts at our live events.
Register now