Version: 6.x-21
This is an older version of Search Guard. Switch to Latest version
Community

Manual installation (Windows)

To quickly set up a Search Guard secured Elasticsearch cluster on Windows:

  1. Install the Search Guard Plugin to Elasticsearch
  2. Download and unzip the demo certificates to the config directory of Elasticsearch
  3. Add the Search Guard minimal configuration to elasticsearch.yml

To use the (optional) Search Guard Kibana plugin which adds security and configuration features to Kibana:

  1. Install the Search Guard Kibana plugin to Kibana
  2. Add the minimal Kibana configuration to kibana.yml

Install Search Guard on Elasticsearch

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

Change to the directory of your Elasticsearch installation and type:

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

For example:

bin/elasticsearch-plugin install -b com.floragunn:search-guard-6:6.2.4-21.0

Replace the version number in the examples above with the exact version number that matches your Elasticsearch installation. A plugin built for Elasticsearch 6.3.0 will not run on Elasticsearch 6.2.4 and vice versa.

An overview of all available Search Guard versions can be found on the Search Guard Version Matrix page.

For offline installation and more details, see the Search Guard installation chapter

Download and install the Search Guard demo certificates

Download the certificates zip file, unpack it and place all files in the following directory:

<ES installation directory>/config

Add the minimal Search Guard configuration

Add the following minimal Search Guard configuration to elasticsearch.yml:

copy

searchguard.ssl.transport.pemcert_filepath: esnode.pem
searchguard.ssl.transport.pemkey_filepath: esnode-key.pem
searchguard.ssl.transport.pemtrustedcas_filepath: root-ca.pem
searchguard.ssl.transport.enforce_hostname_verification: false
searchguard.ssl.http.enabled: true
searchguard.ssl.http.pemcert_filepath: esnode.pem
searchguard.ssl.http.pemkey_filepath: esnode-key.pem
searchguard.ssl.http.pemtrustedcas_filepath: root-ca.pem
searchguard.allow_unsafe_democertificates: true
searchguard.allow_default_init_sgindex: true
searchguard.authcz.admin_dn:
  - CN=kirk,OU=client,O=client,L=test,C=de
searchguard.enable_snapshot_restore_privilege: true
searchguard.check_snapshot_restore_write_privileges: true
searchguard.restapi.roles_enabled: ["sg_all_access"]

Restart your node(s) for the changes to take effect.

Testing the Elasticsearch installation

  • Open https://localhost: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.

Applying configuration changes

The Search Guard configuration, like users, roles and permissions, is stored in a dedicated index in Elasticsearch, the Search Guard Index.

Changes to the Search Guard configuration must be applied to this index by either

  • Using the Kibana Configuration GUI (Enterprise feature)
  • Using the sgadmin command line tool with the generated admin certificate

For using the Kibana Configuration GUI you need to install the Search Guard Kibana Plugin, as described below.

If you want to use the sgadmin tool:

  • Apply your changes to the demo configuration files located in <Elasticsearch directory>/plugins/search-guard-6/sgconfig
  • Execute sgadmin to upload the changed configuration to Search Guard

To execute sgadmin, first cd into

<Elasticsearch directory>/plugins/search-guard-6/tools

And execute:

sgadmin.bat -cd ..\sgconfig -key ..\..\..\config\kirk-key.pem -cert ..\..\..\config\kirk.pem -cacert ..\..\..\config\root-ca.pem -nhnv -icl

This will read the contents of the configuration files in <Elasticsearch directory>/plugins/search-guard-6/sgconfig and upload the contents to the Search Guard index.

The sgadmin tool is very powerful and offers a lot of features to manage any Search Guard installation. For more information about sgadmin, head over to the Using sgadmin chapter.

Install Search Guard on Kibana

The Search Guard Kibana plugin adds authentication, multi tenancy and the Search Guard configuration GUI to Kibana.

  • Download the Search Guard Kibana plugin zip file matching your exact Kibana version from Maven
  • Stop Kibana
  • cd into your Kibana installaton directory.
  • Execute: bin/kibana-plugin install file:///path/to/search-guard-kibana-plugin-<version>.zip.

Add the Search Guard Kibana configuration

If you’ve used the demo configuration to initializing Search Guard as outlined above, add the following lines to your kibana.yml and restart Kibana:

# Use HTTPS instead of HTTP
elasticsearch.url: "https://localhost:9200"

# Configure the Kibana internal server user
elasticsearch.username: "kibanaserver"
elasticsearch.password: "kibanaserver"

# Disable SSL verification because we use self-signed demo certificates
elasticsearch.ssl.verificationMode: none

# Whitelist the Search Guard Multi Tenancy Header
elasticsearch.requestHeadersWhitelist: [ "Authorization", "sgtenant" ]

Start Kibana

After Kibana is started, it will begin optimizing and caching browser bundles. This process may take a few minutes and cannot be skipped. After the plugin is installed and optimized, Kibana will continue to start.

Testing the Kibana installation

  • Open http://localhost:5601/.
  • You should be redirected to the Kibana login page
  • On the login dialogue, use admin as username and admin as password.

If everything is set up correctly, you should see three new navigation entries on the left pane:

Applying configuration changes

The Search Guard configuration GUI allows you to edit

  • Search Guard Roles - define access permissions to indices and types
  • Action Groups - define groups of access permissions
  • Role Mappings - Assign users by username or their backend roles to Search Guard roles
  • Internal User Database - An authentication backend that stores users directly in Elasticsearch

Furthermore you can view your currently active license, upload a new license if it has expired, and display the Search Guard system status.

Where to go next

If you have not already done so, make yourself familiar with the Search Guard Main Concepts.

After that, configure roles and access permissions by either modifying the configuration files and uploading them via sgadmin, or use the Kibana configuration GUI to change them directly.

If you want to use more sophisticated authentication methods like Active Directory, LDAP, Kerberos or JWT, configure your existing authentication and authorisation backends in sg_config.yml.

For fine-grained access control on document- and field level, use the Search Guard Document and field level security module.

If you need to stay compliant with security regulations like GDPR, HIPAA, PCI, ISO or SOX, use the Search Guard Audit Logging to generate and store audit trails.

And if you need to support multiple tenants in Kibana, use Kibana Multitenancy to separate Visualizations and Dashboards by tenant.