Siren Platform User Guide

Search Guard management user interface configuration 

Siren Investigate includes an optional user interface for the Search Guard REST Management API add-on ; to use it, the Siren Investigate back end has to connect to the Elasticsearch cluster using a PEM client certificate with administrative privileges.

Add-on installation

To install the Search Guard REST Management API add-on it is required to download the correct jar for your Elasticsearch / Search Guard version from and copy it to the plugins/search-guard-<version> folder of each node in the cluster.

To access the API it is required to use a client certificate with administrative privileges; to enable optional client certificate authentication on the REST interface, ensure that the following option is present in elasticsearch.yml:

searchguard.ssl.http.clientauth_mode: OPTIONAL

After the plugin has been copied and the configuration updated, the nodes must be restarted; a rolling restart is enough to install the add-on.


When using this add-on, ensure that the sgadmin configuration folder contains only the sg_config.yml file, otherwise sgadmin will replace users, roles, action groups and mappings that may have been modified through the API.

Siren Investigate configuration

Copy the client certificate and its key to a folder readable by Siren Investigate (for example pki); then add the following parameters to the investigate_access_control configuration section:

  • admin_role: The Search Guard role that has access to the Search Guard management UI (investigate_admin by default).

  • backends.searchguard.admin.ssl.cert: Path to the administrative client certificate bundle in PEM format.

  • backends.searchguard.admin.ssl.key: Path to the administrative client certificate key in PEM format.

  • backends.searchguard.admin.ssl.keyPassphrase: The passphrase of the administrative client certificate key. Not required if the key is not encrypted.

For example:

  enabled: true
    enabled: true
  admin_role: investigate_admin
    password: '12345678123456781234567812345678'
    secure: false
      admin.ssl.cert: pki/searchguard/CN=sgadmin.crtfull.pem
      admin.ssl.key: pki/searchguard/CN=sgadmin.key.pem
      admin.ssl.keyPassphrase: password

Note that the administrative client certificate bundle must contain both the full CA chain and the client certificate; if using certificates generated by the TLS generation service, the file name will be CN=sgadmin.crtfull.pem, otherwise it is possible to generate the bundle manually by using cat, for example:

$ cat user.crt.pem ca-chain.pem > user.crtfull.pem
Access control: authentication

After the certificate is set up, restart Siren Investigate, login with a user having an administrative role, click the apps button, then click Access control and finally Authentication.

The Access control app

The Authentication section enables you to browse, edit and create the following Search Guard resources:

  • Internal users
  • Roles
  • Role mappings
  • Action groups

To verify that the application is working correctly, click Roles then click Open; you should see the list of roles defined during the initial Search Guard setup or an authorization error if the certificate is incorrect:

Browsing Search Guard roles

If you get an error upon opening the Authentication app, most probably the client certificate does not contain the full CA chain or the add-on has not been installed correctly, check Elasticsearch and Siren Investigate logs for related errors.

If you experience a Siren Investigate crash when opening the application, ensure that the option investigate_access_control.backends.searchguard.admin.ssl.keyPassphrase is set to the correct password.

Access Control: ACL
The ACL section

The ACL Roles panel in the ACL section enables you to define Siren Investigate roles, which are collections of permissions on saved objects and UI elements. The main purpose of this system is to hide and block access to end users and avoid unauthorized changes to configuration objects or use of certain parts of the system:

  • UI elements - applications, for example: Timelion, Access control, Siren Alert
  • UI elements - specific functionalities, for example: export CSV feature.
  • UI elements - Siren Investigate sections, for example: discover, management.
  • Saved objects on unauthorized indices, for example: dashboards, searches.

There are two kinds of rules:

  • Rules: Set permissions for saved objects.
  • UI rules: Set permissions to view different user interface elements.

The everyone role defines permissions for all the users in the system, and is mapped by default to any user logged in Siren Investigate; by default it grants all users read only access to the Siren Investigate configuration (Advanced settings), saved searches and index patterns as well as permission to view all applications and UI elements.

The everyone role

Denying access to certain saved objects like saved search using the first sets of rules is usually transparent to the user which means that for them, those objects are not visible anywhere in Siren Investigate.

Usually it is not required to create explicit UI rules for the dashboard application as access to specific dashboards can be restricted through saved object rules.

Denying access to an application like Timelion or a Siren Investigate section like management will hide the navigation menu elements, block access at the root level and display an error.

Blocked Timelion application and Siren Investigate management section

When the user tries to access app/timelion, the following error is shown.

Blocked timelion error

When the user tries to access /app/kibana#/management, the following error is shown.

Blocked Siren Investigate management section error

For most setups it makes sense to grant view permissions on visualizations as well, then set specific permissions on dashboards and dashboard groups for each role.

To define a new role, click Create role, then set the following parameters:

  • Role ID: The ID of the role (for example sirenuser); must be a lowercase alphanumeric string.
  • Backend roles: A list of Search Guard roles that will be mapped to this Siren Investigate role (for example sirenuser).
  • Rules: A list of rules on saved object types.

Each rule is defined by three parameters:

  • Action: Allow or deny.
  • Permission: The permission to allow or deny.
  • Context: The saved object type on which the permission must be enforced.
The Create role button
Saving a role
Object permissions

In addition to role level permissions, it is possible to define permissions on specific objects by going to ManagementSave Objects and clicking the permissions button next to an object:

The object permissions button

The object permissions form enables you to set the owner of the object and custom access rules.

By default, the owner is set to the user that created the object; the owner has all permissions on the created object; it is possible to unset the owner of an object by leaving the field blank and clicking the Save button.

Custom access rules can be used to grant access to an object that would be otherwise hidden; for example, if everyone is not granted to display dashboards but you want to display the Overview dashboard to all users, visit the object permissions form for the Overview dashboard and set the View permission for everyone to Allow.

If everyone can see dashboards but you would like to hide the IT dashboard to users, set the View permission for everyone to Deny.

The object permissions form

Users are not allowed to view or edit the following types unless they have permission to do so. But they will be retrieved and executed by the backend if used by a visualization:

  • Query
  • Query templates
  • Datasource

Search results

    No results found