Configuring Investigate to work with Search Guard

This section describes the minimal configuration that is required to integrate a Siren Investigate instance with an Elasticsearch cluster that is configured as described in Search Guard integration .

Preparing PKI files

By convention, certificates and PKI-related files are stored in a folder named pki, which is located inside the directory where Siren Investigate was extracted.

Before you proceed with the configuration, create a pki folder at the same level as the config folder, if it does not already exist and copy the following files into it:

  • chain-ca.pem: a PEM encoded file containing a CA certificate bundle that can validate the certificates installed in the Elasticsearch cluster.

If you want to use the optional Search Guard configuration UI, you must also copy the administrative certificate and key to this directory.

If required, it is possible to put PKI related files in any location that is readable by the user the Investigate process is running as. When copying the Search Guard administrative certificates for use in Investigate, make sure they are not readable by everyone.

Make sure that the Investigate configuration file is only readable by the user Investigate is running as.

Configuration settings

Backend user credentials

Update the config/investigate.yml file to specify the credentials of the sirenserver user, for example:

elasticsearch.username: 'sirenserver'
elasticsearch.password: 'password'

Elasticsearch URL

Make sure that elasticsearch.url starts with https:// and that the correct port is specified, for example:

elasticsearch.url: 'https://localhost:9200'

Verification settings

To validate the Elasticsearch certificate, specify the path to the CA bundle in elasticsearch.ssl.certificateAuthorities and set the elasticsearch.ssl.verificationMode parameter to certificate, for example:

elasticsearch.ssl.certificateAuthorities: 'pki/chain-ca.pem'
elasticsearch.ssl.verificationMode: certificate

If your certificate configuration allows it, you can enable hostname verification by setting elasticsearch.ssl.verificationMode to full.

Access control settings

To enable authentication support in Siren Investigate, you must enable the bundled investigate_access_control plugin and configure a few settings.

The following is an example of a minimal configuration:

investigate_access_control:
  enabled: true
  acl:
    enabled: true
  admin_role: investigate_admin
  backend: searchguard
  cookie:
    secure: true
    password: '12345678123456781234567812345678'

Options

  • enabled: set to true.

  • acl.enabled: set to true.

  • admin_role: users with this role will be given full access to the Siren Investigate configuration sections.

  • backend: set to searchguard.

  • cookie.password: A 32-character-long alphanumeric string that is used to derive the key that encrypts and signs cookies. Make sure to customize this password as it can be used to decrypt session cookies.

  • cookie.secure: if set to true, the cookie will be transmitted by the browser only if the request is being sent via HTTPS. Defaults to true.

Ensure that you personalize the session cookie password.

Additional configuration options

  • session.ttl: The lifetime of the session in milliseconds. If not set, the session will last as long as the session cookie is valid. Defaults to 3600000 (1 hour).

  • session.keepAlive: If set to true, every time a request is received within the session lifetime, the session lifetime will be extended by session.ttl. Defaults to true.

  • cookie.password: A 32 characters long alphanumeric string used to derive the key used to encrypt and sign cookies.

  • cookie.ttl: The lifetime of the session cookie in milliseconds. If not set, the cookie will expire when the browser is closed, which is the recommended setting. Note that browsers may not remove session cookies when a tab is closed or even across restarts, so you should set session.ttl for additional protection. Defaults to null.

  • cookie.name: The name of the session cookie. Defaults to kac.

  • acl.index: The Elasticsearch index in which access control rules and saved objects metadata will be stored (.sirenaccess by default).

After you change the configuration file restart Siren Investigate. If the configuration is correct, an authentication dialog opens when the system restarts.

Authentication dialog

You can now log in as an user with the investigate_admin role, for example, sirenadmin.

Next steps

If you need support for authentication mechanisms other than basic HTTP, refer to Additional authentication mechanisms.

Otherwise, please refer to Configuring ACL in Siren Investigate to complete the Siren Investigate access control configuration.