Skip to main content
Mitratech Success Center

Elasticsearch with Search Guard

Search Guard provides Elasticsearch users with encryption, authentication, authorization, audit logging and multi-tenancy. The following documentation outlines how to install Search Guard for your TeamConnect instance.

Search Guard is optional and can be toggled on or off in the TeamConnect installer. For the standard Elasticsearch installation without Search Guard, please see Elasticsearch Setup.

This documentation covers a basic installation of Search Guard for TeamConnect Global Search. For more information on generating your own security certificates or configuring Search Guard roles, please see the plugin documentation here: http://floragunncom.github.io/search-guard-docs/.

Important: Users upgrading from previous versions of Elasticsearch must re-index their instances. Preliminary testing finds that it takes roughly one hour per 4GB for indexing. This number will vary based on the types of files present in the index. 

For Linux

The following instructions detail a RedHat installation via the Elasticsearch file. If your system is unable to perform this type of installation, please contact Mitratech Support at support@mitratech.com.

    1. Download the RPM file from https://www.elastic.co/downloads/pas...icsearch-5-3-0. TeamConnect is only certified against Elasticsearch 5.3.0. Later 5.3.x patches and     updates will be supported. No updates outside of the 5.3.x line will be supported.

    2. yum install the elasticsearch.xxxxx.rpm or rpm –Uvh elasticsearch.xxxxx.rpm

    3. chkconfig –add elasticsearch to have Elasticsearch start on boot. 

For the following steps, the paths listed below should be accurate to your installation. If not, find the elasticsearch/bin folder and substitute that path in the directions below.
    1. Run the following command from the root Elasticsearch directory:
         bin\elasticsearch-plugin install mapper-attachments
         This plug-in provides the 'attachment' field type to Elasticsearch, thereby allowing it to index to content of documents like PDF files and Microsoft Word files.

    2. Configure properties as detailed in Elasticsearch Configuration.

    3. Start elasticsearch with: /etc/init.d/elasticsearch start after configuration is set.

For Windows

1. Download the Elasticsearch zip file from the following website:
        https://www.elastic.co/downloads/elasticsearch 
    Note: If you are looking for an older version of ES, look here: https://www.elastic.co/downloads/past-releases 

2. Unzip the file in your directory of choice. Having a dedicated folder not in Program Files is usually a good choice. (e.g. C:\...\Apache\Elasticsearch)

3. Navigate to your Elasticsearch /bin either through the command line using Windows Explorer and typing cmd in the top bar.
        The directory should be similar to  C:\...\app\Apache\Elasticsearch\elasticsearch-5.3\bin 

4. Install the Mapper Attachments Plugin
This plugin is used to parse documents that are sent over from TeamConnect. It must be installed for documents to index properly. https://github.com/elastic/elasticse...er-attachments

5. Run the following command from the root Elasticsearch directory:
         bin\elasticsearch-plugin install mapper-attachments

6. Configure properties as detailed in Elasticsearch Configuration.

Running Elasticsearch on Windows is fairly simple, just navigate to the bin directory of your Elasticsearch installation and start the elasticsearch.bat file.
Elasticsearch picks up your java path from your environment variables, so you'll have to add the JAVA_HOME variable pointed to Java 1.8.
    In order to set the heap size for ES, you must define an environment variable for it.

  1.         From the Start menu or Windows Explorer, right click on Computer and select Properties"
  2.         From the left nav, select "Advanced System Settings".
  3.         In System Properties, select "Environment Variables".
  4.         Under "System variables", add a new variable with:
                      name: ES_HEAP_SIZE
                      value: 1g

          5.          Select "OK" and "apply"
 


The steps from here forward apply to both Linux and Windows users seeking to install Search Guard.


Installing Search Guard


1. Install the Search Guard plugin.
    Open the command prompt and change directory to your Elasticsearch folder
    Run the command:
                   bin\elasticsearch-plugin install -b com.floragunn:search-guard-5:5.3.0-12

2. Users will need to create or obtain their own security certificates as these will not be provided by Mitratech. These certificates will need to be in .jks storage format.
        
Note: 

  • The node certificate must have a SAN (Subject Alternative Name) with an OID of 1.2.3.4.5.5
  • For network communication, the SAN must also contain the machine's unique IP address, and the full computer name as a DNS name


3. Implement your configuration and certificate files.
    Place node-keystore.jks & a copy of truststore.jks in the Elasticsearch/config directory
    Place client-keystore.jks & truststore.jks in the directory of your choosing. Please ensure that this directory is accessible by TeamConnect.
    Ensure that the teamconnect.properties file has accurately populated the relevant Search Guard fields. These fields are detailed below in Searchguard Properties in     teamconnect.properties.

4. Close all Java instances. Run the following shell commands, as administrator, from the Elasticsearch\config directory.
    Whitelist your certificates by adding the signing authority to your keytool chain. For example:
        keytool -importcert -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -storepass changeit -alias signing-ca -file signing-ca.crt

5. Update elasticsearch.yml, sg_config.yml, sg_roles.yml, sg_roles_mapping.yml, sg_action_groups.yml and sg_internal_users.yml settings to match appropriately. These files can be found in the TeamConnect/utilities/config folder of your TeamConnect installation. 

Configuring Elasticsearch properties

Place the signing authority, node-keystore.jks & truststore.jks in Elasticsearch/config

Navigate to elasticseach/config & update the elasticsearch.yml settings

  • cluster.name: elasticsearch
    • This setting should match the cluster name in teamconnect.properties
  • node.name: node-0
    • Its recommended that this setting match your certificate name
  • bootstrap.memory_lock: true
  • network.host: 127.0.0.1
  • transport.tcp.port: 9300
    • These two should match the location in teamconnect.properties
  • searchguard.ssl.transport.keystore_filepath: node-keystore.jks
  • searchguard.ssl.transport.keystore_password: changeit
    • Passwords are stored as clear text
  • searchguard.ssl.transport.truststore_filepath: truststore.jks
  • searchguard.ssl.transport.truststore_password: changeit
  • searchguard.ssl.transport.enforce_hostname_verification: false
  • searchguard.ssl.transport.keystore_alias: node-0
    • Set the alias to match the alias of your node's keystore
  • searchguard.authcz.impersonation_dn:

"CN=client1,OU=client,O=client,L=Test,C=DE":
 - '*'

    • This setting configures the admin certificate that you can use with sgadmin

Configuring SearchGuard properties

Navigate to elasticsearch/plugins/search-guard-5/sgconfig. Move the generated utilities/config files into this folder.

SG_INTERNAL_USERS.YML

  • Add the full name of each client keystore as below
    CN=client1,OU=client,O=client,L=Test,C=DE:
         hash: "_transport_only"
  • Add the unencrypted username & bcrypt encrypted password following the format below.
  • The username & hash are the unencrypted elasticsearch.transport.username & elasticsearch.transport.password located in teamconnect.properties
    username.

SG_CONFIG.YML
In this file, add the following lines under authc

transport_auth_domain:
 enabled: true
 order: 2
 http_authenticator:
 authentication_backend:
 type: internal


6. Start Elasticsearch by running "elasticsearch.bat" in  Elasticsearch/bin.

7. Customize your roles & permissions. Then load these settings into elasticsearch in order to initialize the cluster. 
    Open a cmd shell in "Elasticsearch\plugins\search-guard-5\tools"
    Run the command:
    sgadmin -ks ..\..\..\config\node-keystore.jks -kspass changeit -ts ..\..\..\config\truststore.jks -tspass changeit -cd ..\sgconfig -nhnv
   
The following serve as optional parameters for the sgadmin tool:
            -h    elasticsearch hostname, default: localhost
            -p    elasticsearch port, default: 9300 
            -cn  clustername, default: elasticsearch

Re-run this command every time searchguard config changes are made.

Configuring Searchguard Properties


1. Navigate to elasticsearch/plugins/search-guard-5/sgconfig
Add the full name of each client keystore as below
CN=client1,OU=client,O=client,L=Test,C=DE:
     hash: "_transport_only"

2. Add the unencrypted username & brcrypt encrypted password following the format below.

The fields can be found as elasticsearch.transport.username & elasticsearch.transport.password in teamconnect.properties
username: hash: $2y$10$X1B8ncqRb1B.5SrjMEjM2e9wOtggziRF0AlceAmL0In.sMaeDe91i
Add the keystore name & username to the sg_all_access group as below

3. (Optional) Create your own custom role instead of using sg_all_access and add it to SG_ROLES.YML & SG_ROLES_MAPPING.YML
sg_all_access:
     users:
          - admin
          - 'CN=client1,OU=


Searchguard Properties in teamconnect.properties
Property Purpose
elasticsearch.client.keystore.password=[password here] These are the passwords for your keystore and truststore after being run encrypted.
If you generated one from the steps above, retrieve the output using your password.
elasticsearch.client.truststore.password=[password here]
elasticsearch.transport.username= These fields serve as the username and password to be paired with Search Guard for authentication. 
elasticsearch.transport.password=
elasticsearch.keystore.path=config/certs/keystore.jks These are the actual locations of your files.
While you can use absolute path or relative path in listing these, absolute is recommended as best practices.
elasticsearch.truststore.path=config/certs/truststore.jks
elasticsearch.encryption.enabled=YES Set this value to "YES" to enable Search Guard. Set this value to "NO" to disable Search Guard.
elasticsearch.client.notification.email= The email set here will receive certificate expiration notices.


Note: These fields can be configured in the TeamConnect Installer and do not have to be edited manually. For more information on this, please see Running the Installer in the TeamConnect Installation Help.

  • Was this article helpful?