Submit Feedback

Securing Elasticsearch

The very first thing you must do to secure Elasticsearch is enable X-Pack Security. After that you can begin configuring authentication and encrypted communication.

note

Elasticsearch 6.x: If you’re using Elasticsearch 6, you need a Liferay Enterprise Search (LES) subscription and the Liferay Enterprise Search Security application to use Elastic’s X-Pack Security. Starting with the Liferay Connector to Elasticsearch 7 (available on the Customer Downloads portal and bundled in Liferay 7.3+), support for Elastic’s X-Pack security is included by default. To integrate with Elastic’s X-Pack monitoring, LES is required.

Enable X-Pack Security

To enable security, add this setting in each Elasticsearch node’s [Elasticsearch Home]/config/elasticsearch.yml file:

xpack.security.enabled: true

Now you can set up X-Pack users.

Set Up X-Pack Users

In a system using X-Pack, these built-in X-Pack users are important:

kibana_system
elastic

On your Elasticsearch server, use the setup-passwords command to set passwords for them:

./bin/elasticsearch-setup-passwords interactive

note

The configurations shown below assume all passwords are set to liferay. Use your own passwords for your installation.

note

To update a built-in user’s password, use Kibana’s UI or the Change Password API.

Encrypting Elasticsearch Communication

Enabling Transport Layer Security (TLS) involves generating node certificates and keys and applying them to the Elasticsearch servers and Liferay servers.

Generate Node Certificates

Generate a certificate for each node, or generate a certificate to be used on all nodes and clients—like Liferay. Alternatively, use your certificate authority to obtain node certificates.

Generate X-Pack certificate authority using the X-Pack’s certutil command:
```
./bin/elasticsearch-certutil ca --ca-dn CN=elastic-ca
```
This generates a file called elastic-stack-ca.p12.

To generate the certificate authority cert and private key in PEM format,
```
./bin/elasticsearch-certutil ca --pem --ca-dn CN=elastic-ca
```
Move the certificate authority file(s) file to the [Elasticsearch Home]/config/certs folder.
Generate X.509 certificates and private keys using the CA you created:

To generate certificates and keys in PKCS#12 format, run
```
./bin/elasticsearch-certutil cert --ca config/certs/elastic-stack-ca.p12 --ca-pass liferay --dns localhost --ip 127.0.0.1 --name elastic-nodes
```
To generate certificates and keys in PEM format, run
```
./bin/elasticsearch-certutil cert --pem --ca-cert config/certs/ca.crt --ca-key config/certs/ca.key --dns localhost --ip 127.0.0.1 --name elastic-nodes
```
To generate PEM format node certificates and keys from the PKSC#12 certificate authority, run
```
./bin/elasticsearch-certutil cert --pem --ca config/certs/elastic-stack-ca.p12 --ca-pass liferay --dns localhost --ip 127.0.0.1 --name elastic-nodes
```
note

On Liferay 7.3+ only the following keystore types can be used in the Elasticsearch connector configuration.

To generate a certificate that works with multiple hosts (for example to use the same certificate on all Elasticsearch and Liferay servers), use comma-separated lists when listing the DNS names and IP addresses:
```
./bin/elasticsearch-certutil cert --ca config/certs/elastic-stack-ca.p12 --ca-pass liferay --dns localhost,example.com,es-node1,es-node2,es-node3 --ip 127.0.0.1,<IPv4-address-2>,<IPv4-address-3>,<IPv4-address-4>
```
The elasticsearch-certutil cert command generates another file called elastic-nodes.p12 (feel free to name it differently).

note

The certutil command defaults to using the PKCS#12 format for certificate generation, which works with your Elastic Stack 7.x. Kibana 6.x does not work with PKCS#12 certificates, so the --pem option (generates the certificate in PEM format) is important if you’re using Liferay 7.2 and Kibana 6.x with Liferay Enterprise Search Monitoring. The PEM command for each case generates two ZIP files: ca.crt and ca.key, elastic-nodes.crt and elastic-nodes.key. Unzip the archive’ contents in the [Elasticsearch Home]/config/certs folder.
Move elastic-nodes.p12 to the [Elasticsearch Home]/config/certs folder.

Checkpoint: You now have the following files in your [Elasticsearch Home]/config/certs folder:
```
elastic-nodes.p12
elastic-stack-ca.p12
```
or
```
ca.crt
ca.key
elastic-nodes.crt
elastic-nodes.key
```
Copy the files to the same folder on each Elasticsearch node, and to an appropriate location on each Liferay server node.

The certificates and keys are ready to use in your Elasticsearch configuration.

Configure TLS for Elasticsearch

Enable TLS on each node via its [Elasticsearch Home]/config/elasticsearch.yml file.

Enable transport layer TLS with these settings in elasticsearch.yml for inter-node communication:
```
xpack.security.transport.ssl.enabled: true
```

Configure transport layer TLS. Add the certificate, key and certificate authority paths to each node’s elasticsearch.yml:

# PKCS#12
xpack.security.transport.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.keystore.password: liferay
xpack.security.transport.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.truststore.password: liferay
# PEM
#xpack.security.transport.ssl.certificate_authorities: [ "certs/ca.crt" ]
#xpack.security.transport.ssl.certificate: certs/elastic-nodes.crt
#xpack.security.transport.ssl.key: certs/elastic-nodes.key

xpack.security.transport.ssl.verification_mode: certificate

The example paths above assume you added the certificates to [Elasticsearch Home]/config/certs.

Enable TLS on the HTTP layer to encrypt client communication:
```
xpack.security.http.ssl.enabled: true
```

Configure HTTP layer TLS. Add the certificate, key, and certificate authority paths to each node’s elasticsearch.yml:

# PKCS#12
xpack.security.http.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.keystore.password: liferay
xpack.security.http.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.truststore.password: liferay
# PEM
#xpack.security.http.ssl.certificate_authorities: [ "certs/ca.crt" ]
#xpack.security.http.ssl.certificate: certs/elastic-nodes.crt
#xpack.security.http.ssl.key: certs/elastic-nodes.key

Example Elasticsearch Security Configuration

Here is the complete Elasticsearch configuration (elasticsearch.yml; applies equally to Elasticsearch 6.5.x+):

cluster.name: LiferayElasticsearchCluster

# X-Pack Security
xpack.security.enabled: true

## TLS/SSL settings for Transport layer (PKCS#12)
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.keystore.password: liferay
xpack.security.transport.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.truststore.password: liferay
xpack.security.transport.ssl.verification_mode: certificate

# TLS/SSL settings for HTTP layer (PKCS#12)
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.keystore.password: liferay
xpack.security.http.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.truststore.password: liferay

# Comment out when Kibana and Liferay's X-Pack Monitoring are also configured
#xpack.monitoring.collection.enabled: true

Configure a Secure Connection to Elasticsearch in Liferay

On Liferay, security can be configured in the Control Panel or using a configuration file. Navigate to Control Panel → Configuration → System Settings. Find the Search category and click on the Elasticsearch 7 entry on Liferay 7.3+ or X-Pack Security entry on Liferay 7.2. You can enter the property values here, but it’s more common to use a configuration file deployed to [Liferay Home]/osgi/configs.

Important

The Elasticsearch 7 system settings entry and corresponding configuration file are also used for configuring the connection to Elasticsearch 8.

The exact contents of the file depend on your X-Pack setup. The password must match the one you set during the X-Pack user password setup above.

The certificate and key files referenced here are the same ones used on the Elasticsearch server nodes. Copy them to the Liferay server and update their paths in the configuration accordingly.

Besides configuring TLS, you also enable authentication in the settings below by setting authenticationEnabled/requiresAuthentication to true and providing the credentials for the Elasticsearch user used by Liferay to authenticate into Elasticsearch.

When you’re finished configuring security, restart Elasticsearch. These steps require a full Elasticsearch cluster restart.

Configure a Secure Connection to Elasticsearch in Liferay 7.3 and 7.4

tip

Installing Elasticsearch and Connecting to Elasticsearch show enabling and configuring security; see them for the 7.3+ applicable security configurations.

The Elasticsearch connector bundled with Liferay 7.3+ includes X-Pack Security support. See the Java 11 security documentation for a list of the supported key store types that can be used in the Elasticsearch connector configuration.

Create a file called

com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config

and populate the file like this:

operationMode="REMOTE"
productionModeEnabled=B"true"
username="elastic"
password="liferay"
authenticationEnabled=B"true"
httpSSLEnabled=B"true"
networkHostAddresses=["https://localhost:9200"]
truststorePassword="liferay"
truststorePath="/PATH/TO/elastic-nodes.p12"
truststoreType="pkcs12"

Configure a Secure Connection to Elasticsearch in Liferay 7.2

All Liferay connectors to Elasticsearch 7 and above include X-Pack Security support.

note

If you are on Liferay 7.2 and Elasticsearch 6.x and have a Liferay Enterprise Search subscription, download the “Liferay Enterprise Search Security” application. Install the LPKG file by copying it into the [Liferay Home]/deploy folder.

Create a file called

com.liferay.portal.search.elasticsearch7.configuration.XPackSecurityConfiguration.config

(or com.liferay.portal.search.elasticsearch6.configuration.XPackSecurityConfiguration.config if you are using Elastic Stack 6.x and the Liferay Enterprise Search Security application)

Populate the file like this (PKCS#12):

certificateFormat="PKCS#12"
sslKeystorePath="/PATH/TO/elastic-nodes.p12"
sslKeystorePassword="liferay"
sslTruststorePath="/PATH/TO/elastic-nodes.p12"
sslTruststorePassword="liferay"
requiresAuthentication=B"true"
username="elastic"
password="liferay"
transportSSLVerificationMode="certificate"
transportSSLEnabled=B"true"

Use settings like this if you are using PEM format certificates:

certificateFormat="PEM"
sslKeyPath="/PATH/TO/elastic-nodes.key"
sslCertificatePath="/PATH/TO/elastic-nodes.crt"
requiresAuthentication=B"true"
username="elastic"
password="liferay"
sslCertificateAuthoritiesPaths="/PATH/TO/ca.crt"
transportSSLVerificationMode="certificate"
transportSSLEnabled="true"

Elasticsearch Connector Security Settings in Liferay 7.3 and 7.4

Here’s the complete list of security settings for the Elasticsearch connector in 7.3+ (default values in parentheses):

authenticationEnabled (true): Enable or disable authentication to Elasticsearch with a user name and password.

username (elastic): Set the user name for authenticating to Elasticsearch if Authentication Enabled is checked.

password: Set the password for authenticating to Elasticsearch if Authentication Enabled is checked.

httpSSLEnabled (false): Enable or disable TLS/SSL.

truststoreType (pkcs12): Set the truststore type if HTTP SSL Enabled is checked.

truststorePath (/path/ro/localhost.p12): Set the path to the truststore file if HTTP SSL Enabled is checked.

truststorePassword: Set the password to the truststore if HTTP SSL Enabled is checked.

Enterprise Search Security / X-Pack Security Settings in Liferay 7.2

Here’s the complete list of settings for the X-Pack Security configuration on Liferay 7.2:

sslKeyPath (/path/to/instance.key): Set the path to the PEM encoded file containing the private key.

sslCertificatePath (/path/to/instance.crt): Set the path to a PEM encoded file containing the certificate (or certificate chain) that is presented to clients when they connect. Defaults to /path/to/instance.crt.

sslCertificateAuthoritiesPaths ([“/path/to/ca.crt”]): Provide a list of paths to trusted PEM encoded certificate files.

certificateFormat (PKCS#12): Specify the certificate format (PEM or PKCS#12).

requiresAuthentication (false): If enabled, connections with Elasticsearch/X-Pack are authenticated with the configured user name and password.

username (elastic): If Requires Authentication is enabled, set the user name for authenticating to Elasticsearch is required.

password: If Requires Authentication is enabled, a password is required.

transportSSLVerificationMode (certificate): Specify the verification type (none, certificate, or full) when using LDAP to protect against man in the middle attacks and certificate forgery.

transportSSLEnabled (false): Set or disable TLS/SSL.

sslKeystorePath (/path/to/elastic-certificates.p12): Set the path to the keystore holding the private key and certificate.

sslKeystorePassword: Set the password to the PKCS#12 file.

sslTruststorePath (/path/to/elastic-certificates.p12): Set the path to the truststore file.

sslTruststorePassword: Set the password to the truststore.

Configuring TLS Protocols and Cipher Suites

You can configure TLS properties in Liferay’s JVM to exert control over the TLS protocol version and the cipher suites used in encrypting the Elasticsearch-Liferay connection. You might set these properties in the Tomcat server’s setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -Djdk.tls.client.protocols=TLSv1.2
CATALINA_OPTS="$CATALINA_OPTS -Djdk.tls.client.cipherSuites=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"

Note that these are example values.

These settings work in conjunction with the corresponding XPack settings.

If you’re configuring the REST Client connection on Liferay 7.3 or 7.4, use HTTP layer settings like these in elasticsearch.yml:

xpack.security.http.ssl.supported_protocols: [ "TLSv1.2" ]
xpack.security.http.ssl.cipher_suites : TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

If you’re configuring the Transport Client on Liferay 7.1 and 7.2, use transport settings like these in elaticsearch.yml:

xpack.security.transport.ssl.supported_protocols: [ "TLSv1.2" ]
xpack.security.transport.ssl.cipher_suites : TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

Capability:

Resource Type:

Official Documentation

Feature:

Search Engine Installation and Maintenance

Deployment Approach:

Liferay Self-Hosted