Configuring Elasticsearch with Transport Client security

If you're using Elasticsearch and want to use the Transport Client over SSL/TLS, you'll need to complete some additional installation and configuration steps.

This document provides information about implementing Transport Client security using Shield, an Elasticsearch plug-in that provides SSL/TLS encryption for network traffic to and from the Elasticsearch node.

For full details about installing Shield, see https://www.elastic.co/guide/en/shield/shield-1.3/installing-shield.html.

Supported Platforms: 8.4x

Table of Contents

  1. Step 1: Download the Elasticsearch Shield plug-in
  2. Step 2: Unzip installation files
  3. Step 3: Set up user and user roles
  4. Step 4: Configure the Elasticsearch YAML file
  5. Step 5: Configure transport client security settings

Note: For general information about installation and configuration of Elasticsearch, see Installing and Configuring Elasticsearch.

Step 1: Download the Elasticsearch Shield plug-in

The first step is to download the Shield plug-in.

To download the Shield plug-in
  1. Go to the Elasticsearch site (https://www.elastic.co/) and download the Shield feature:
  2. Download the license ZIP file:

    Note: This is the trial license, and can be used for development only. For the Production environment, you'll need to get a license from Elasticsearch support.

  3. Copy the ZIP files to the machine where Elasticsearch is installed.

back to top

Step 2: Unzip installation files

To install the plugins using the ZIP files, run bin/plugin with the -u option.

For example:

  1. Change directory (cd) to the Elasticsearch installation folder.
  2. Run the following two commands:
    1. bin/plugin -i license -u file:///{path_to_file}/license-1.0.0.zip
    2. bin/plugin -i shield -u file:///{path_to_file}/shield-1.3.3.zip

Note: You must specify an absolute path to the ZIP file after the file:// protocol.

back to top

Step 3: Set up user and user roles

The next step is to add user and user roles for the client user.

For detailed documentation about managing Elasticsearch users and user roles, see https://www.elastic.co/guide/en/shield/shield-1.3/_managing_users_in_an_esusers_realm.html.

Note: The Transport client user must have at least the user role of power_user for the container where the Community Manager Scheduled Jobs feature is installed. For the containers that are read-only (only search), the user role user is enough.

  1. CD to the {elasticsearch}/bin/shield folder.
  2. Run the following command to add a user:
    esusers useradd {username} -p {secret}

    For example:

    esusers useradd es_power_user -p Password1
  3. Assign roles to the user. The example below assigns the power_user role to the user es_power_user:
    esusers roles es_power_user -a power_user
  4. If needed, change user password:
    esusers passwd {username} -p {secret}
  5. If needed, remove roles assigned to a user. In the example below, -r removes role admin for user es_admin:
    esusers roles es_admin -r admin
  6. If needed, delete users, using the esusers userdel command:
    userdel {username}

back to top

Step 4: Configure the Elasticsearch YAML file

You'll need to manually change some of the settings in one of the Elasticsearch configuration files, elasticsearch.yml, generally stored in the {elasticsearch_home}/config folder.

You can have Shield installed and enabled but might choose not to enable SSL; for example, if the cluster is within the firewall. If Shield is installed and SSL is disabled, Shield still expects the transport client user authentication header. In the Akana Administration Console, see the Transport Client user settings.

For general information about the elasticsearch.yml file, see https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html.

To configure the Elasticsearch YAML file
  1. Modify the properties in the elasticsearch.yml file, using the examples below (you can copy and paste):
    • Sample YAML with SSL enabled
    • Sample YAML with SSL disabled
  2. Restart the Elasticsearch cluster.

Sample YAML with SSL enabled

shield.enabled: true
shield.ssl.keystore.path: {path}\node01.jks
shield.ssl.keystore.password: changeit
shield.ssl.keystore.key_password: changeit
shield.transport.ssl: true
shield.http.ssl: true
shield.https.ssl: true
shield.ssl.hostname_verification: false
#shield.ssl.hostname_verification.resolve_name: true
#client specific settings
#This enables SSL on the client profile. The default value for this setting is the value of shield.transport.ssl.
transport.profiles.client.ssl: false
#This setting keeps certificate authentication active for node-to-node traffic, but removes the requirement to distribute a signed certificate to transport clients. 
#transport.profiles.client.shield.ssl.client.auth: no
shield.http.ssl.client.auth: optional

Sample YAML with SSL disabled

shield.enabled: true
shield.ssl.keystore.path: C:\SOA\ES\NodeCert\node01.jks
shield.ssl.keystore.password: changeit
shield.ssl.keystore.key_password: changeit
shield.transport.ssl: false
shield.http.ssl: false
shield.https.ssl: false
shield.ssl.hostname_verification: false
#shield.ssl.hostname_verification.resolve_name: true
#client specific settings
#This enables SSL on the client profile. The default value for this setting is the value of shield.transport.ssl.
transport.profiles.client.ssl: false
#This setting keeps certificate authentication active for node-to-node traffic, but removes the requirement to distribute a signed certificate to transport clients. 
#transport.profiles.client.shield.ssl.client.auth: no
shield.http.ssl.client.auth: no

back to top

Step 5: Configure transport client security settings

Follow the steps below.

Note: If Shield is not installed on the Elasticsearch cluster, you don't need to do anything. The default for enabling SSL is false.

To configure the transport client security settings
  1. Log in to the Akana Administration Console.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, scroll down to find the com.akana.es.client.security category. You'll see the settings, as shown below:
    elastic.client.alias
    elastic.client.aliasPassword
    elastic.client.clientUser:
    elastic.client.clientUserPassword:
    elastic.client.enableSSL: false
    elastic.client.keystorePassword
    elastic.client.keystorePath
  4. Change the values as needed. Sample settings when SSL is disabled are shown below:

    Elasticsearch configuration settings (SSL disabled)

    Sample settings when SSL is enabled are shown below:

    Elasticsearch configuration settings with SSL enabled

  5. Click Apply Changes.

Notes:

  • By default, SSL is disabled.
  • If SSL is disabled on the Elasticsearch cluster and Shield is installed, you must at minimum provide values for clientUser and clientUserPassword.
  • The transport client user is added in the above steps, with appropriate roles.

back to top

Version 8.2:

Version 8.0: