Search Guard FLX overview

Search Guard FLX is the next-generation security and authentication plugin for Elasticsearch now supported by Siren Investigate. It provides fine‑grained access control, pluggable authentication / authorization backends, auditing, and TLS encryption. This page explains how to set up an Elasticsearch cluster secured by Search Guard FLX and how to configure Siren Investigate to connect to it.

You are viewing the updated documentation for Search Guard FLX. The previous "Search Guard Classic" is deprecated in Siren Investigate. New deployments should use FLX. If you are upgrading from Classic, see the migration guidance below.

Migration from Search Guard Classic

If you previously used Search Guard Classic:

  1. Plan downtime (or a rolling restart window) – FLX requires updating config files and possibly certificate DNs.

  2. Export any custom role / action group definitions from Classic sg_roles* and sg_action_groups* configuration.

  3. Re‑generate or validate TLS certificates. FLX supports the same PKI approach; you can usually reuse certificates if the DNs remain consistent, but review FLX documentation for any new mandatory OIDs or SAN requirements.

  4. Translate Classic configuration blocks (roles, role mappings, authc/authz) into the FLX YAML layout. Names can stay the same for backward compatibility.

  5. Remove Classic plugin from each Elasticsearch node and install the FLX plugin matching the exact Elasticsearch version.

  6. Apply FLX configuration (bootstrap if first install). Use the FLX admin tool (formerly sgadmin) to upload the new config set.

  7. Restart nodes (rolling) and verify cluster health and FLX license state.

  8. Update Siren Investigate configuration to point to the secured endpoints (see integration section). Ensure any header‑based auth or proxy settings are aligned with the chosen FLX authc chain.

  9. Test: login, index pattern discovery, dashboards, and Global Search.

Keep a backup of your Classic configuration and keystore before migrating. Do not mix Classic and FLX plugins in the same cluster.

In this section

Setting up security certificates for FLX

Integrating Search Guard FLX

Upgrading to / maintaining Search Guard FLX

Configuring Investigate with Search Guard FLX

Overview

Search Guard FLX adds a flexible authentication chain model. Typical steps to secure a cluster:

  1. Install the plugin on every Elasticsearch node (all nodes must run the same FLX version matching the Elasticsearch version).

  2. Generate or provide a certificate authority (CA) and issue:

    1. Node certificates (used for transport & HTTP TLS)

    2. Admin certificate (for the FLX administration tool)

    3. Optional client certificates (if using mutual TLS)

  3. Enable TLS on both transport and HTTP layers in elasticsearch.yml.

  4. Prepare FLX configuration files (roles, role mappings, authc/authz backends, action groups, tenants) and upload them with the FLX admin tool.

  5. Configure Siren Investigate:

    1. Set elasticsearch.url to the HTTPS endpoint.

    2. Add CA certificate paths (array supported) so the TLS handshake validates the cluster.

    3. Configure credentials or client certificate depending on chosen auth backend (basic, JWT/OIDC, SAML, proxy auth, Kerberos, etc.).

    4. (Optional) Enable multi-tenancy features if used in FLX (map tenants to Siren spaces/dataspaces as needed).

  6. Validate by logging in and running queries.

Authentication chains

FLX lets you chain multiple authc modules (e.g. client cert → JWT → basic). Order matters: a successful earlier module can short‑circuit later ones. When designing the chain:

  • Place cheap, stateless mechanisms first (e.g. header / token checks) before interactive ones (basic / SAML redirects).

  • Ensure only one module performs user mapping for a given request path to avoid ambiguity.

  • Use explicit challenge modules (e.g. basic) last.

Roles and permissions

Roles combine index permissions, cluster permissions, and (optionally) tenant access. In Siren Investigate contexts:

  • Dashboards, saved searches, and index pattern visibility depend on the underlying indices permitted to the role.

  • Use the least privilege principle: only grant the indices required by a workspace/dataspace.

  • If using joins / federated relations, ensure both sides’ indices are allowed.

Auditing

Enable FLX audit logging to record security events (logins, failed authentications, permission denials). Forward audit indices to a secured cluster or archive according to compliance policies.

Best practices

  • Keep FLX and Elasticsearch versions aligned; upgrade FLX immediately after (or with) an Elasticsearch upgrade.

  • Rotate TLS certificates before expiry; monitor with automation.

  • Use multiple CA certs in siren investigate config if you operate a rolling CA rotation.

  • Regularly review dormant roles and remove unused permissions.

  • Test failover scenarios (node loss) with FLX enabled to ensure bootstrap / quorum settings are correct.

Troubleshooting

Symptom Possible cause Action

401 / 403 errors in UI

Missing role mapping or insufficient index privileges

Map user/role; verify action groups.

TLS handshake failure

Wrong CA chain or hostname mismatch

Reissue certs; confirm SAN entries.

Admin tool rejected

Certificate DN not authorized

Add DN to admin distinguished names list.

Multi-tenancy not visible

Tenant feature disabled or role lacks tenant access

Enable tenant module; add tenant permission to role.

JWT/OIDC auth loops

Misconfigured redirect URI or clock skew

Correct callback URL; sync system clocks.

Further reading

Refer to the official Search Guard FLX documentation for exhaustive configuration directives and advanced scenarios (attribute-based security, custom authenticators, dynamic role mappings).