Installing Search Guard (TCE 6.1)
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.
- For local instances, make sure the Elasticsearch x-pack plugin is disabled/removed.
- Make sure you have followed the steps to install Elasticsearch.
Installing Search Guard Plug-in
To install the Search Guard plugin:
- Open the command prompt and change the directory to your Elasticsearch folder.
- Run the following command:
bin\elasticsearch-plugin install -b com.floragunn:search-guard-5:5.3.0-12
Creating and Installing Security Certificates
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:
- Download the scripts from the SearchGuard GitHub https://github.com/floragunncom/search-guard-ssl.
- Navigate to the example-pki-scripts folder.
- 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
- 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)
- 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
- example.sh creates the signing authorities, node keystore, client keystore, and truststore files. These files will need to be added
- Close all Java instances.
- Whitelist your certificates by adding the signing authority to your Java keytool chain.
- 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
- 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>
- Place the signing authority, node keystore and truststore files (for example, signing-ca.crt, node-0-keystore.jks & truststore.jks) into the
elasticsearch-5.3.0/config directory. - 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-5/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:
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
- Add the full name of each client 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"
- 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>
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. - 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)
roles:
- esdev
Note: The hashed password can be created by navigating to elasticsearch-5.3.0/plugins/search-guard-5/tools and invoking the hash.bat
script file in command line to encrypt the password.
Configuring SG_ROLES_MAPPING.YML
- Create a role for the keystore name as below (where keystore name = "esdev") as follows:
esdev:
users:
- esdev - Create a role for the username as below (where username = "username") as follows:
username:
users:
- username - Add the admin & username to the sg_all_access group as follows:
sg_all_access:
users:
- admin
- username
Configuring SG_ROLES.YML
Create a role for the keystore name (where keystore name = "esdev") as follows:
esdev:
cluster:
- CLUSTER_COMPOSITE_OPS
- "indices:data/read/scroll*"
indices:
'<index_name>':
'*':
- 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
- 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.
- Navigate to elasticsearch-5.3.0\plugins\search-guard-5\tools.
- Run the command:
sgadmin -cd <path_to_elasticsearch>\elasticsearch-5.3.0\plugins\search-guard-5\sgconfig -ts <path_to_elasticsearch>\elasticsearch-5.3.0\config\<truststore_name>.jks -ks <path_to_elasticsearch>\elasticsearch-5.3.0\config\<keystore_name>.jks
For example, sgadmin -ks ..\..\..\config\node-0-keystore.jks -kspass changeit -ts ..\..\..\config\truststore.jks -tspass changeit -cd ..\sgconfig -nhnv
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.