Search Guard - Enterprise Security for Elasticsearch

Version: Search Guard 5 / This is an older version of Search Guard. Switch to Latest version

Installation

General

The basic installation procedure is to:

  1. Stop Elasticsearch
  2. Install Search Guard
  3. Execute the demo configuration script
  4. Restart Elasticsearch.
  5. Initialise the Search Guard index by running sgadmin

Ensure that your Java Virtual Machine is supported

  • We support only OpenJDK 7/8 or Oracle JVM 7/8.
  • There is no support for IBM VM or any other vendor than OpenJDK/Oracle JVM

Installing Search Guard

Search Guard can be installed like any other Elasticsearch plugin by using the elasticsearch-plugin command.

  • Download the Search Guard version matching your Elasticsearch version
  • Change to the directory of your Elasticsearch installation and type:
bin/elasticsearch-plugin install -b file:///path/to/search-guard-5-5.6.16-19.4.zip

Additional permissions dialogue

Since ES 2.2, you will see the following warning message when installating Search Guard and/or Search Guard SSL. Confirm it by pressing ‘y’:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@     WARNING: plugin requires additional permissions     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission loadLibrary.*
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.security.SecurityPermission getProperty.ssl.KeyManagerFactory.algorithm
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.

Quickstart: Configuring and Initializing Search Guard

Search Guard requires the following minumum pre-requisited to run:

  • TLS certificates for securing transport- and REST-traffic
  • TLS configuration settings in elasticsearch.yml
  • Initialization of the Search Guard index

Search Guard ships with scripts to aid you with the initial setup. Before moving your installation to production, please read the moving Search Guard to production chapter.

Configuring Search Guard

  • Stop Elasticsearch

  • cd into <Elasticsearch directory>/plugins/search-guard-5/tools

  • Execute ./install_demo_configuration.sh, chmod the script first if necessary.

This will generate the truststore and two keystore files. You can find them in the config directory of your Elasticsearch installation:

  • truststore.jks—the root CA and intermediate/signing CA.
  • keystore.jks—the node certificate.
  • kirk.jks—the admin certificate required for running sgadmin

The config directory should now look like:

elasticsearch-5.5.0
│
└─── config
    │   elasticsearch.yml
    │   log4j2.properties
    │   keystore.jks
    │   kirk.jks
    │   truststore.jks
    ├─── scripts
    │    │   ...
    │ ...

The script will also add the TLS configuration to the config/elasticsearch.yml file automatically.

Initializing Search Guard

In order to upload the demo configuration with users, roles and permissions:

  • Start Elasticsearch

  • cd into <Elasticsearch directory>/plugins/search-guard-5/tools

  • Execute ./sgadmin_demo.sh, chmod the script if necessary first

This will execute sgadmin and populate the Search Guard configuration index with the files contained in the plugins/search-guard-<version>/sgconfig directory. If you want to play around with different configuration settings, you can change the files in the sgconfig directory directly. After that, just execute ./sgadmin_demo.sh again for the changes to take effect.

Testing the installation

Using curl

  • Execute curl --insecure -u admin:admin 'https://localhost:9200/_searchguard/authinfo?pretty'
  • This will print out information about the user admin in JSON format on the console.

Using a browser

  • Open https://<hostname>:9200/_searchguard/authinfo.
  • Accept the self-signed demo TLS certificate.
  • In the HTTP Basic Authentication dialogue, use admin as username and admin as password.
  • This will print out information about the user admin in JSON format.

Installing enterprise modules

If you want to use any of the enterprise modules, simply download the respective module jar file and place it in the folder

<ES installation directory>/plugins/search-guard-5

After that, restart your nodes for the changes to take effect.

LDAP- and Active Directory Authentication/Authorisation:

LDAP module v5.6-13 for Elasticsearch 5.6.x

LDAP and Active Directory documentation

Kerberos/SPNEGO Authentication/Authorisation:

Kerberos/SPNEGO module v5.0-4 for Elasticsearch 5.6.x

Kerberos/SPNEGO documentation

JWT Authentication/Authorisation:

JWT module v5.0-7 for Elasticsearch 5.6.x

JSON Web token documentation

Document- and field level security:

Document- and field level module v5.6-11 for Elasticsearch 5.6.x

Document and field level security documentation

Audit logging:

Audit log module v5.3-7 for Elasticsearch 5.6.x

Audit Logging documentation

REST management API:

REST management module v5.3-7 for Elasticsearch 5.6.x

REST management API documentation

Kibana multi tenancy module:

Multi tenancy management module v5.4-5 for Elasticsearch 5.6.x

Kibana Multitenancy documentation

Most of these modules require additional configuration settings. Please see the respective sections of this document for further information.