OpenID Connect authentication support

This section offers an overview of how to integrate Siren Investigate with the OpenID Connect authentication support provided by Search Guard FLX.

Prerequisites

Before you begin, ensure that you have completed the following steps:

Set up security certificates
Integrate Search Guard FLX

When a user opens an OpenID Connect-enabled instance of Siren Investigate, they will be redirected to the Identity Provider (IdP) to enter their credentials. The IdP then generates an access token that is used by Siren Investigate to retrieve an ID token. Both tokens are encoded by using JSON and are signed with a public key.

The fields in the ID token (claims) are then parsed to retrieve the following information:

a unique user identifier (username, subject name or email address);
the roles granted to the users by the Identity Provider (backend roles).

The configuration defined in sg_role_mappings.yml is then used to map the backend roles to one or more Elasticsearch roles (the ones defined in sg_roles.yml).

In order to validate tokens, both Investigate and Elasticsearch will need to fetch the public keys from the Identity Provider’s discovery URL; this URL ends with /.well-known/openid-configuration and can usually be retrieved from the configuration UI of the provider.

Before proceeding with the configuration, you will need the following information:

the discovery URL of your Identity Provider;
the name of the ID token claim that contains the unique user identifier;
the name of the ID token claim that contains the backend roles.

Search Guard FLX configuration

In order to configure Search Guard FLX to work with an OpenID Connect compliant identity provider, you’ll need to add a jwt authentication domain to the sg_authc.yml file alongside the existing domains defined in the auth_domains section.

An OpenID Connect authentication domain requires the following configuration options:

jwt.signing.jwks_endpoint.url: An endpoint which serves JWKS documents. Search Guard will automatically refresh the document whenever an unknown key (identified by the kid claim) is encountered. or
jwt.signing.jwks_from_openid_configuration.url: An OIDC .well-known/openid-configuration endpoint which is used to retrieve keys as JWKS. Search Guard will automatically refresh the JWKS document whenever an unknown key (identified by the kid claim) is encountered.
user_mapping.user_name: the jwt token claim that contains the unique username
user_mapping.roles: the jwt token claim that contains the backend roles.

For additional options please refer to the Search Guard FLX documentation; a reference example follows:

auth_domains:
  - type: "basic/internal_users_db"
  - type: jwt
    jwt.signing.jwks_from_openid_configuration.url: "http://localhost:8080/realms/siren/.well-known/openid-configuration"
    jwt.required_audience: "investigate"
    user_mapping.user_name.from: jwt.preferred_username
    user_mapping.roles.from.json_path: $.jwt.roles[?(@ != 'offline_access' && @ != 'uma_authorization' && @ != 'default-roles-siren')]

The order of the auth_domains is important here. The jwt domain should be lower than the basic_internal_auth_domain as otherwise all basic auth request will trigger a warning every time Investigate checks the connectivity to Elasticsearch.

After you edit the sg_authc.yml file, upload it to the cluster by using sgctl.

Configuring Siren Investigate

To enable OpenID Connect support in Siren Investigate, you will need to set the following variables under the investigate_access_control section:

public_url: the URL used by end users to open Investigate, including the base path; for example, if Investigate is running behind a reverse proxy at https://investigate.local/investigate, public_url must be set to https://investigate.local/investigate.
backends.searchguard.authenticator: set to openid.
backends.searchguard.openid.discovery_url: set to the same discovery URL specified in the Search Guard Classic configuration.
backends.searchguard.openid.client_id: set to the OpenID Connect client ID configured in the Identity Provider.
backends.searchguard.openid.client_secret: set to the password of the client_id specified in the previous step.
backends.searchguard.openid.scope: an array of additional scopes to request. Some identity providers might require the profile scope to return user information in the ID token, most will require the offline_access scope to return a refresh token.
backends.searchguard.openid.refresh_interval: if set to a number of seconds greater than 0, Investigate will refresh its access token and refresh user information periodically to keep the session alive. If not set, the Investigate user session will terminate once the access token expires. Should be lower than the access token lifetime.
session.backend: by default, Investigate will store user tokens in an encrypted browser cookie, however this might block the initiation of a session if the tokens are too large to be contained in a 5K cookie. When setting this option to true, Investigate will store the tokens in memory and put only a reference to the session in an encrypted browser cookie. If you are using multiple Investigate instances behind a reverse proxy and the option is enabled, make sure that session affinity is enabled when using this option, as the individual Investigate instance won’t share backend sessions between them.

A minimal configuration follows:

investigate_access_control:
  enabled: true
  public_url: "https://investigate.local/investigate"
  acl:
    enabled: true
  admin_role: investigate_admin
  session:
    backend: false
  cookie:
    name: 'kac'
    password: '12345678123456781234567812345678'
    secure: true
  backend: searchguard
  backends:
    searchguard:
      authenticator: openid
      openid:
        discovery_url: "http://localhost:8080/realms/siren/.well-known/openid-configuration"
        client_id: "CLIENT_ID_FROM_IDENTITY_PROVIDER"
        client_secret: "CLIENT_SECRET_FROM_IDENTITY_PROVIDER"

Restart Investigate after applying the changes to the investigate_access_control section.

If the configuration is correct, when opening Investigate you should be redirected to the Identity Provider login page and after entering your credentials be redirected to Investigate and logged in.

When logged in, the user information tooltip should:

list the expected Search Guard FLX roles (displayed as Elasticsearch roles)
list all the roles declared in the ID token roles claim as DLS roles.

<em>User information</em>

Next steps

Configuring ACL in Siren Investigate