Configuring Delegate PKI authentication

This section offers an overview of how to integrate Siren Investigate with the Delegate PKI authentication mechanism, which is available in Elasticsearch Gold subscriptions and higher.

Prerequisites

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

Mapping client certificate subjects to Siren Investigate roles

To use Siren Investigate with the default configuration, you will need to map at least one subject to the following Elasticsearch roles:

  • The investigate_admin role

  • The investigate_user role

For general information about role mapping in Elasticsearch, refer to the Mapping users and groups to roles section of the Elasticsearch documentation.

For example, if you want to map the subject whose distinguished name is CN=sirenadmin,OU=admins to the investigate_admin role, the following request can be used:

curl -k -XPUT -u elastic https://localhost:9200/_security/role_mapping/investigate_admin -H "Content-Type: application/json" -d '{
  "roles" : [ "investigate_admin" ],
  "rules" : {
    "field" : {
      "dn" : "CN=sirenadmin,OU=admins"
    }
  },
  "enabled": true
}'

Configuring Siren Investigate

After the Delegate PKI support is configured, the HTTPS server in Siren Investigate is responsible for authenticating client certificates that are sent by end users.

If a certificate is valid, Siren Investigate sends the certificate information to the Elasticsearch Delegate PKI API to obtain an access token, which is then sent in each request to Elasticsearch to authenticate search queries.

The exchange of certificate information with an access token is allowed exclusively to the investigate_system role, which is granted the delegate_pki permission.

  1. To allow Siren Investigate to authenticate TLS certificates, copy the following files to the config/pki subdirectory of your Siren Investigate instance:

    • The certification authority bundle that is used to validate client certificates in X.509 format (referred to as ca.pem in the examples).

    • If needed, a file containing a revocation list in X.509 format (referred to as crl.pem in the examples).

  2. Set the following additional variables in the investigate.yml file:

    • server.ssl.requestClientCertificate: Set the value to true to enable client certificate authentication.

    • server.ssl.certificateAuthorities: The list of certificate authority bundle files that are used to validate the client certificates.

    • server.ssl.crl: The list of certificate revocation list files.

    • investigate_access_control.backend: Set the value to xpack.

    • backends.xpack.authenticator: Set the value to delegate-pki.

      The following is an example of a basic configuration:

      # Native HTTPS support and client authentication settings
server.ssl.enabled: true
server.ssl.certificate: 'pki/investigate.pem'
server.ssl.key: 'pki/investigate.key'
server.ssl.keyPassphrase: password
server.ssl.requestClientCertificate: true
server.ssl.certificateAuthorities:
- 'pki/ca.pem'
server.ssl.crl:
- 'pki/crl.pem'

# Elasticsearch connection settings
elasticsearch.url: "https://localhost:9200"
elasticsearch.ssl.certificateAuthorities:
- 'pki/ca.pem'
elasticsearch.ssl.verificationMode: certificate
elasticsearch.username: "sirenserver"
elasticsearch.password: "password"

# Access control settings
investigate_access_control:
  enabled: true
  acl:
    enabled: true
  admin_role: investigate_admin
  cookie:
    password: '12345678123456781234567812345678'
    secure: true
  backend: xpack
  backends:
    xpack:
      authenticator: delegate-pki

  3. After you have updated the investigate.yml file, restart Siren Investigate.

  4. Validate that the configuration is correct. Open Siren Investigate and the system will prompt you to provide a client certificate. If the certificate that you provide is correct, you will be logged in.

Next steps

Configuring ACL in Siren Investigate