Skip to main content
Mitratech Success Center

Client Support Center

Need help? Click a product group below to select your application and get access to knowledge articles, webinars, training content, and release notes or to contact our support team.

Authorized users - log in to create a ticket, view tickets status and check your success plan details.

 

Installing Search Guard (TCE 6.2)

  1. Last updated
  2. Save as PDF

If you are not using Search Guard, skip this section. These instructions apply to both Linux and Microsoft Windows.

Before you begin:

  • Elasticsearch requires Java 8. Make sure that your JAVA_HOME path points to JDK8.
  • Make sure the Elasticsearch x-pack plugin is disabled/removed.
  • Make sure you have followed the steps to install Elasticsearch for TeamConnect 6.2.
  • Make sure that a port is opened in the firewall for the ports being used.

Installing Search Guard Plug-in 

To install the Search Guard plugin:

  1. Open the command prompt and change the directory to your Elasticsearch folder.
  2. Run the following command:
    bin\elasticsearch-plugin install -b com.floragunn:search-guard-7:7.1.1-37.0.0

Creating and Installing Security Certificates

Certificates can be generated in one of two ways. Mitratech Hosting can generate the certificates manually, or you can generate them using the following instructions. OpenSSL is required to generate certificates. Windows users can use the terminal built into SourceTree to run the shell scripts. These certificates need to be in .jks storage format.

To create security certificates:   

  1. Download the scripts from the SearchGuard GitHub https://github.com/floragunncom/search-guard-ssl. Select the 5.3.0 branch since certificates are the same as for that release.
  2. Navigate to the example-pki-scripts folder.
  3. Modify the node script for network communication:
    • Edit gen_node_cert.sh and modify the "$BIN_PATH" -genkey command and the "$BIN_PATH" -certreq.
    • Use the following example and update the highlighted DNS and IP addresses to match the targeted machine that will host Elasticsearch:
       -ext san=dns:<YourMachineName>,dns:localhost,ip:10.5.90.50,ip:127.0.0.1,oid:1.2.3.4.5.5 
      where <YourMachineName> is in the format change-this-dns-address.example.com
  4. Modify example.sh to only run the following shell scripts:
    • ./clean.sh
    • ./gen_root_ca.sh capass <Password>  where <Password> is the password to be used (for example, changeit)
    • ./gen_node_cert.sh <NodeNumber> <Password> capass where <NodeNumber> is the node name and <Password> is the password to be used (for example, 0 and changeit)
    • ./gen_client_node_cert.sh <ClientUsername> <Password> capass where <ClientUsername> is the username and <Password> is the password to be used (for example, esdev and changeit)
  5. Run example.sh to generate a new sets of files.
    • example.sh creates the signing authorities, node keystore, client keystore, and truststore files. These files will need to be added
      to your system chain in order to recognize the validity of the certificates.
    • gen_node_cert.sh creates the individual node keystore for the node specified (for example, node-0-keystore.jks) and a truststore.
    • gen_client_node_cert.sh creates the client keystore (for example,  esdev-keystore.jks) and a truststore.
    • gen_root_ca.sh creates new signing authorities. These files sign all keystores on their creation. These files will be located in the /ca subdirectory.

      Important
      • 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
  6. Close all Java instances.
  7. Whitelist your certificates by adding the signing authority to your Java keytool chain.
  8. Run the following shell command as administrator from the Elasticsearch\config directory:
    • keytool -importcert -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -storepass changeit -alias signing-ca -file signing-ca.crt
  9. Optionally, clean up any duplicate certificate aliases by running the following shell command as administrator from the Elasticsearch\config directory:
    • keytool -delete -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -storepass changeit -alias <old alias name>
  10. Place the signing authority, node keystore and truststore files (for example, signing-ca.crt, node-0-keystore.jks & truststore.jks) into the
    elasticsearch-7.1.1/config directory.
  11. Place the client certificate, client keystore and truststore files (for example, signing-ca.crt, esdev-keystore.jks and truststore.jks) in a directory on
    your PC that is accessible by TeamConnect (for example, config/certs).

Configuring TeamConnect Properties and Elasticsearch Properties

Follow the instructions for Configuring Elasticsearch Properties (elasticsearch.yml) and Configuring TeamConnect Properties (teamconnect.properties).

Configuring Search Guard 

After Search Guard is installed, navigate to the <elasticsearch root>/plugins/search-guard-7/sgconfig folder. 

You can run the following commands against your database to get the values mentioned in the steps below.

value command
<index_name> select setting_value from y_system_setting where setting_key = 'ElasticSearchUUID'
<searchguard_password> The BCrypt encrypted version of elasticsearch.transport.password in TeamConnect.properties
<searchguard_username> Located in TeamConnect.properties as elasticsearch.transport.username

To configure Search Guard, modify the following files:

Note: YML file formats have changed for Elasticsearch 7.1.1. All YML files must contain the following at the top:

---
_sg_meta:
type: "roles"
config_version: 2

Configuring SG_CONFIG.YML

Add the following change to configure transport level authentication under authc:

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

Configuring SG_INTERNAL_USERS.YML
  1. Add the full name of each node certificate as follows where <node_number> is the node specified when generating the certificate above
    (for example, "node-0"):

    CN=<node_number>,OU=client,O=client,L=Test,C=DE:
    hash: "_transport_only"
     
  2. Add the transport username and password from teamconnect.properties (the roles will be defined in the next file). For example, if the searchguard_username= "username", the entry would be as follows:

    username:
      hash: "<hashed_password>"
      backend_    roles:
         - "username"

    where <hashed_password> is "password".

    The username and hashed_password are the unencrypted elasticsearch.transport.username and elasticsearch.transport.password located in
    teamconnect.properties.
  3. Add the client keystore and password. For example, if the client keystore= "esdev" the entry would be as follows:

    esdev:
      hash: "<hashed_password> (where <hashed_password> was "changeit" when generating key)"
      backend_roles:
         - "esdev"

    Note: The hashed password can be created by navigating to elasticsearch-7.1.1/plugins/search-guard-7/tools and invoking the hash.bat
    script file in command line to encrypt the password.
Configuring SG_ROLES_MAPPING.YML
  1. Create a role for the client keystore name as below (where client keystore name = "esdev") as follows:
    esdev:
      users:
         - "esdev"
  2. Create a role for the username as below (where username = "username") as follows:
    username:
      users:
         - "username"
  3. Add the admin & username to the sgs_all_access group as follows:
    SGS_ALL_ACCESS:
      backend_roles:
         - "admin"
         - "username"
Configuring SG_ROLES.YML

Create a role for the client keystore name (where client keystore name = "esdev") as follows:

esdev:
  cluster_permissions:
    - CLUSTER_COMPOSITE_OPS
    - "indices:data/read/scroll*"
  index_permissions:
    - index_patterns:
         - "<index_name>*"
      allowed_actions:  
            - UNLIMITED

(where <index_name> is the value from the database) 

 

Note: It's recommended to create a 1:1 individual role for each user. It also helps tracking index permissions if the role name matches the user name.

Loading Search Guard Settings into Elasticsearch Cluster

  1. Start Elasticsearch. The binary is located in the elasticsearch/bin folder. Linux users may have to run from Elasticseach's root directory. If you encounter any bootstrap check failures, see Elasticsearch Bootstrap Checks.
  2. Navigate to elasticsearch-7.1.1\plugins\search-guard-7\tools.
  3. Run the command:
    sgadmin -cd <path_to_elasticsearch>\elasticsearch-7.1.1\plugins\search-guard-7\sgconfig -ts <path_to_elasticsearch>\elasticsearch-7.1.1\config\<truststore_name>.jks -ks <path_to_elasticsearch>\elasticsearch-7.1.1\config\<keystore_name>.jks

    For example, sgadmin -ks ..\..\..\config\esdev-keystore.jks -kspass changeit -ts ..\..\..\config\truststore.jks -tspass changeit -cd ..\sgconfig -nhnv

    Note: The keystore references should be the path to your client keystore (not the node keystore).


Modify the certificate paths and/or add the following optional parameters as needed:

-h elasticsearch hostname, default: localhost
-p elasticsearch port, default: 9300 (NOT the http port!)
-cn clustername, default: elasticsearch

You are now ready to verify the configuration and creating indices.

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.