Manual installation (Windows)
To quickly set up a Search Guard secured Elasticsearch cluster on Windows:
- Install the Search Guard Plugin to Elasticsearch
- Download and unzip the demo certificates to the config directory of Elasticsearch
- 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:
- Install the Search Guard Kibana plugin to Kibana
- Add the minimal Kibana configuration to
Install Search Guard on Elasticsearch
Search Guard can be installed like any other Elasticsearch plugin by using the
Change to the directory of your Elasticsearch installation and type:
bin/elasticsearch-plugin install -b com.floragunn:search-guard-6:<version>
bin/elasticsearch-plugin install -b com.floragunn:search-guard-6:6.2.3-22.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.2.3 will not run on Elasticsearch 6.1.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
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
- Accept the self-signed demo TLS certificate.
- In the HTTP Basic Authentication dialogue, use
adminas username and
- This will print out information about the user
adminin 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
- Execute sgadmin to upload the changed configuration to Search Guard
To execute sgadmin, first cd into
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.
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" ]
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
- You should be redirected to the Kibana login page
- On the login dialogue, use
adminas username and
If everything is set up correctly, you should see three new navigation entries on the left pane:
- Search Guard - the Search Guard configuration GUI
- Tenants - to select a tenant for Kibana Multitenancy
- Logout - to end your current session
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.
- Using and defining action groups
- Defining roles and permissions
- Mapping users to Search Guard roles
- Adding users to the internal user database
If you want to use more sophisticated authentication methods like Active Directory, LDAP, Kerberos or JWT, configure your existing authentication and authorisation backends in
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.