Integrating Search Guard FLX

This section describes how to install and configure Search Guard FLX on an Elasticsearch cluster and integrate it with Siren Investigate. If you need to migrate from a previous Classic deployment, see the upgrade / migration page.

Before you begin

  • Ensure that Siren Investigate is running with HTTPS enabled. For more information, see Enabling HTTPS in Siren Investigate.

  • Ensure that you have prepared all required security certificates (cluster CA, node certs, admin cert, optional client certs). For more information, see Setting up security certificates.

  • Download the FLX admin tool compatible with your Elasticsearch / FLX version from the official Search Guard download portal.

Installing Search Guard FLX

A first installation requires a rolling restart (or full restart for single‑node) because TLS must be enabled on the transport layer across all nodes.

Disable shard allocation (multi‑node clusters)

Optionally disable shard allocation to speed up the restart sequence:

./sgctl.sh rest put _cluster/settings --json '{"persistent":{"cluster.routing.allocation.enable": "none"}}'

or using curl:

curl -s -XPUT 'http://localhost:9200/_cluster/settings?pretty' -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "cluster.routing.allocation.enable": "none"
  }
}
'

Install the plugin

Install the Search Guard FLX plugin on every node (run inside the Elasticsearch home directory):

bin/elasticsearch-plugin install -b <link to a compatible Search Guard FLX release>

If Elasticsearch was installed from a package, the command is usually at /usr/share/elasticsearch/bin/elasticsearch-plugin.

After installation, copy these files into each node’s config directory:

  • CA bundle (e.g. chain-ca.pem).

  • Node certificate (e.g. node01.crtfull.pem).

  • Node private key (e.g. node01.key.pem).

  • (Optional) Admin certificate/key pair if not already present on the node where you will run the admin tool.

Configure elasticsearch.yml

Add (or adjust) the following minimal FLX TLS and admin settings (adapt filenames, passwords):

# Disable built‑in security if required for your distribution/version
xpack.security.enabled: false

searchguard.ssl.transport.pemcert_filepath: "node01.crtfull.pem"
searchguard.ssl.transport.pemkey_filepath: "node01.key.pem"
searchguard.ssl.transport.pemkey_password: "password"
searchguard.ssl.transport.pemtrustedcas_filepath: "chain-ca.pem"
searchguard.ssl.transport.enforce_hostname_verification: true

searchguard.ssl.http.enabled: true
searchguard.ssl.http.pemcert_filepath: "node01.crtfull.pem"
searchguard.ssl.http.pemkey_filepath: "node01.key.pem"
searchguard.ssl.http.pemkey_password: "password"
searchguard.ssl.http.pemtrustedcas_filepath: "chain-ca.pem"

# Distinguished names (DNs) of admin certificates allowed to upload FLX configs
searchguard.authcz.admin_dn:
  - "CN=sgadmin"

# Allow Siren Federate custom headers
searchguard.allow_custom_headers: "_siren_.*"

Ensure files in the config directory are readable only by the Elasticsearch user.

Restart each node (rolling) and verify logs for successful FLX initialization.

Re‑enable shard allocation

If shard allocation was disabled:

./sgctl.sh rest put _cluster/settings --json '{"persistent":{"cluster.routing.allocation.enable": "all"}}'

Search Guard FLX configuration

FLX configuration (authc chain, users / backends, roles, action groups, tenants) resides in a set of YAML files uploaded to a special index via the admin tool.

Typical files:

  • sg_config.yml – general / auth chain.

  • sg_action_groups.yml – reusable permission groupings.

  • sg_roles.yml – role definitions.

  • sg_internal_users.yml – internal user store (if used).

  • sg_roles_mapping.yml – map external backend roles / users to FLX roles.

  • sg_tenants.yml – tenant definitions (required even if tenants unused).

Sample (role excerpt):

investigate_user:
  cluster_permissions:
    - CLUSTER_COMPOSITE_OPS_RO
    - CLUSTER_INTERNAL_FEDERATE
  index_permissions:
    - index_patterns:
        - 'data-*'
      allowed_actions:
        - READ
        - VIEW_INDEX_METADATA

Action group names and structure may evolve between Classic and FLX. Always verify against the FLX version matrix.

Connecting to the cluster

The admin tool must connect to the cluster over HTTPS. If using a client certificate for authentication, provide the certificate and key files. Example command:

sgctl connect localhost --ca-cart /path/to/root-ca.pem --cert /path/to/admin-cert.pem --key /path/to/admin-cert-private-key.pem

Upload configuration

Use the sgctl command line tool to upload your configuration files. Replace the paths and filenames as needed:

sgctl update-config path/to/config/dir/

This command uploads all YAML configuration files from the sgconfig directory to the cluster. For more options and details, consult the Search Guard FLX documentation.

Check output for success messages (index created / config updated).

Verify authentication

Example auth info request (basic auth shown; replace admin credentials):

curl --cacert chain-ca.pem -u admin:password "https://localhost:9200/_searchguard/authinfo?pretty"

A successful response lists the authenticated user and mapped roles.

Next steps

Configuring Investigate with Search Guard FLX