search-guard-docs

Official documentation for Search Guard, the Elasticsearch security suite

This project is maintained by floragunncom

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 you Java Virtual Machine is supported

Installing Search Guard

Search Guard can be installed like any other Elasticsearch plugin. Replace the version number in the following examples with the exact version number that matches your Elasticsearch installation. A plugin built for ES 5.4.3 will not run on ES 5.5.0 and vice versa.

Change to the directory of your Elasticsearch installation and type:

bin/elasticsearch-plugin install -b com.floragunn:search-guard-5:<version>

For example:

bin/elasticsearch-plugin install -b com.floragunn:search-guard-5:5.5.0-14

Run bin/elasticsearch-plugin as the user that owns all of the Elasticsearch files.

In order to find the most recent Search Guard version for your Elasticsearch installation, please refer to our version matrix.

After the installation you see a folder called “search-guard-5” in the plugin directory of your Elasticsearch installation.

If you’re running Elasticsearch 2.x:

For Search Guard 2, you need to install Search Guard SSL first and after that Search Guard. Change to the directory of your Elasticsearch installation and type:

bin/plugin install -b com.floragunn/search-guard-ssl/2.4.5.21
bin/plugin install -b com.floragunn/search-guard-2/2.4.5.14

After the installation you should see a folder called “search-guard-2” in the plugin directory of your Elasticsearch installation.

Offline installation

If you are behind a firewall and need to perform an offline installation, follow these steps:

bin/elasticsearch-plugin install -b file:///path/to/search-guard-5-<version>.zip

If you’re running Elasticsearch 2.x:

bin/plugin install -b file:///location/of/search-guard-ssl-<version>.zip
bin/plugin install -b file:///location/of/search-guard-2-<version>.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:

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

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

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:

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

Using a browser

Installing enterprise modules

If you want to use any of the enterprise modules, simply download the respective module jar file from Maven. When downloading, choose “jar with dependencies” and place it in the folder

or

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

LDAP- and Active Directory Authentication/Authorisation:

All versions on maven central

https://github.com/floragunncom/search-guard-authbackend-ldap

LDAP and Active Directory documentation

Kerberos/SPNEGO Authentication/Authorisation:

All versions on maven central

https://github.com/floragunncom/search-guard-auth-http-kerberos

Kerberos/SPNEGO documentation

JWT Authentication/Authorisation:

All versions on maven central

https://github.com/floragunncom/search-guard-authbackend-jwt

JSON Web token documentation

Document- and field level security:

All versions on maven central

https://github.com/floragunncom/search-guard-module-dlsfls

Document and field level security documentation

Audit logging:

All versions on maven central

https://github.com/floragunncom/search-guard-module-auditlog

Audit Logging documentation

REST management API:

All versions on maven central

https://github.com/floragunncom/search-guard-rest-api

REST management API documentation

Kibana multi tenancy module:

All versions on maven central

https://github.com/floragunncom/search-guard-module-kibana-multitenancy

Kibana Multitenancy documentation

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