Manual installation (Windows)
Content
- Install Search Guard on Elasticsearch
- Download and install the Search Guard demo certificates
- Add the minimal Search Guard configuration
- Testing the Elasticsearch installation
- Applying configuration changes
- Install Search Guard on Kibana
- Add the Search Guard Kibana configuration
- Start Kibana
- Testing the Kibana installation
- Applying configuration changes
- Where to go next
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
kibana.yml
Install Search Guard on Elasticsearch
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-7-<version>.zip
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
:
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: ["SGS_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 andadmin
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-7/sgconfig
- Execute sgadmin to upload the changed configuration to Search Guard
To execute sgadmin, first cd into
<Elasticsearch directory>/plugins/search-guard-7/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-7/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 matching your exact Kibana version from Maven
- Stop Kibana
- cd into your Kibana installaton directory
- Execute: `bin/kibana-plugin install file:///path/to/kibana-plugin.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.hosts: "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" ]
# X-Pack security needs to be disabled for Search Guard to work properly
xpack.security.enabled: false
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 andadmin
as password.
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 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.