> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Elasticsearch and Kibana

> This guide explains how to secure a self-managed Elasticsearch and Kibana deployment used by GermainUX.

Service
`Enterprise`

Availability
2024.1

> **[Secure Elasticsearch and Kibana](#overview)**
>
> Harden a self-managed stack

> **[Before You Begin](#before-you-begin)**
>
> Requirements before hardening

> **[Prepare Certificates](#prepare-certificates)**
>
> Create and place TLS certificates

> **[Configure Elasticsearch Security](#configure-elasticsearch-security)**
>
> Restrict access to the cluster

## Overview

This guide explains how to secure a self-managed Elasticsearch and Kibana deployment used by GermainUX.

It covers:

* Authentication and authorization
* TLS between Elasticsearch nodes
* HTTPS between GermainUX and Elasticsearch
* HTTPS between users and Kibana
* Certificate trust
* Secure credential storage
* Deployment validation
* Rollback planning

The examples assume Elasticsearch and Kibana run through Docker Compose. Adapt file paths and secret-management methods to your infrastructure.

> [!NOTE]
>
> Use the Elasticsearch and Kibana versions supported by your GermainUX release. Do not copy version numbers from an older example configuration.

### Communication to Secure

| Connection | Default port | Required protection |
| - | - | - |
| Elasticsearch node to Elasticsearch node | `9300` | Mutual TLS and certificate verification |
| GermainUX Enterprise to Elasticsearch | `9200` | HTTPS, certificate validation, and authentication |
| Kibana to Elasticsearch | `9200` | HTTPS, certificate validation, and dedicated credentials |
| User browser to Kibana | `5601` | HTTPS and user authentication |

Do not expose ports `9200`, `9300`, or `5601` to untrusted networks.

### Security Requirements

Before production use:

* Enable Elasticsearch security.
* Encrypt node-to-node transport.
* Encrypt Elasticsearch HTTP traffic.
* Encrypt browser traffic to Kibana.
* Validate certificate chains and hostnames.
* Use dedicated service accounts.

> **Show all 11**
>
> * Apply least-privilege roles.
> * Store passwords in keystores or an approved secret manager.
> * Restrict access through firewalls or security groups.
> * Monitor certificate expiration.
> * Configure backups and test recovery.

Do not use the `elastic` superuser as the permanent GermainUX or Kibana service account.

## Before You Begin

### Confirm Compatibility

Confirm with Germain Software:

* Supported Elasticsearch version
* Supported Kibana version
* Compatible GermainUX Elasticsearch plugin
* Required TLS settings
* Required GermainUX index permissions
* Supported authentication methods
* Required restart sequence

Elasticsearch and Kibana must use compatible versions.

### Prepare a Maintenance Window

Securing an existing unsecured cluster changes its endpoints from HTTP to HTTPS and may restart or replace nodes.

Before proceeding:

**1. Schedule a maintenance window**

**2. Take a current Elasticsearch snapshot**

**3. Verify that the snapshot completed**

**4. Record the current configuration**

**5. Back up Docker Compose files**

**6. Back up Elasticsearch and Kibana configuration**

**7. Export or record GermainUX connection settings**

**8. Prepare and validate a rollback plan**

**9. Stop monitoring ingestion during the final cutover when required**

### Obtain Certificates

Use certificates issued by:

* Your organization’s internal certificate authority
* A trusted public certificate authority
* Elastic’s certificate utility, when approved

Certificates must include the correct DNS names and, where required, IP addresses in their Subject Alternative Names.

Prepare certificates for:

* Elasticsearch transport TLS
* Elasticsearch HTTP TLS
* Kibana HTTPS

The same certificate should not automatically be reused for every purpose unless your security team approves that design.

## Prepare Certificates

### Convert a PKCS#12 File—When Required

If your organization provides a `.pfx` or `.p12` file, extract the private key and certificate only when the target configuration requires PEM files:

```text theme={null}
openssl pkcs12 \
  -in kibana.example.com.pfx \
  -nocerts \
  -out key.pem
```

```text theme={null}
openssl pkcs12 \
  -in kibana.example.com.pfx \
  -nokeys \
  -out cert.pem
```

Avoid `-nodes` for production private keys unless the deployment requires an unencrypted key and compensating protections are in place.

Restrict private-key permissions:

```text theme={null}
chmod 600 key.pem
```

Never store private keys or certificate passwords in source control.

### Import the Certificate Authority Into Java

GermainUX Enterprise must trust the certificate authority that signs the Elasticsearch HTTPS certificate.

Import the CA certificate—not merely an individual leaf certificate—into the Java truststore used by GermainUX:

```text theme={null}
keytool -importcert \
  -trustcacerts \
  -alias germain-elasticsearch-ca \
  -file /path/to/ca.pem \
  -keystore /path/to/cacerts
```

Use your organization’s truststore password and confirm the certificate fingerprint before accepting it.

For containers, mount a dedicated truststore rather than modifying an image manually:

```text theme={null}
volumes:
  - /secure/path/cacerts:/etc/ssl/certs/java/cacerts:ro
```

## Configure Elasticsearch Security

### Enable Authentication

Enable Elasticsearch security using the supported configuration for your Elasticsearch version:

```text theme={null}
xpack.security.enabled: "true"
```

For a new Elasticsearch 8.x deployment, security may be enabled automatically. Confirm the actual cluster configuration rather than enabling duplicate or conflicting settings.

### Configure Transport TLS

Multi-node production clusters require encrypted and authenticated node-to-node communication.

Example:

```text theme={null}
xpack.security.transport.ssl.enabled: "true"
xpack.security.transport.ssl.verification_mode: "full"
xpack.security.transport.ssl.client_authentication: "required"
xpack.security.transport.ssl.keystore.path: "/usr/share/elasticsearch/config/transport.p12"
xpack.security.transport.ssl.truststore.path: "/usr/share/elasticsearch/config/transport.p12"
```

Use certificates containing the correct node DNS names.

Do not use:

```text theme={null}
xpack.security.transport.ssl.verification_mode: "none"
```

Disabling certificate verification defeats an essential part of transport security.

### Configure HTTP TLS

Enable HTTPS for GermainUX, Kibana, and other Elasticsearch clients:

```text theme={null}
xpack.security.http.ssl.enabled: "true"
xpack.security.http.ssl.verification_mode: "full"
xpack.security.http.ssl.keystore.path: "/usr/share/elasticsearch/config/http.p12"
xpack.security.http.ssl.truststore.path: "/usr/share/elasticsearch/config/http.p12"
```

Client authentication can remain optional when clients authenticate with service accounts, API keys, or usernames and passwords:

```text theme={null}
xpack.security.http.ssl.client_authentication: "optional"
```

Use `required` only when mutual TLS has been designed and configured for every client.

### Store Certificate Passwords Securely

Add PKCS#12 passwords to the Elasticsearch keystore rather than placing them in Docker Compose.

For each Elasticsearch node:

```text theme={null}
bin/elasticsearch-keystore add \
  xpack.security.transport.ssl.keystore.secure_password
```

```text theme={null}
bin/elasticsearch-keystore add \
  xpack.security.transport.ssl.truststore.secure_password
```

```text theme={null}
bin/elasticsearch-keystore add \
  xpack.security.http.ssl.keystore.secure_password
```

```text theme={null}
bin/elasticsearch-keystore add \
  xpack.security.http.ssl.truststore.secure_password
```

Persist and mount each node’s keystore securely.

### Mount Security Files

Example:

```text theme={null}
volumes:
  - /secure/elasticsearch/http.p12:/usr/share/elasticsearch/config/http.p12:ro
  - /secure/elasticsearch/transport.p12:/usr/share/elasticsearch/config/transport.p12:ro
  - /secure/elasticsearch/elasticsearch.keystore:/usr/share/elasticsearch/config/elasticsearch.keystore:ro
```

Do not make certificate directories or keystores world-readable.

## Configure Accounts and Roles

Create separate identities for:

| Identity | Purpose |
| - | - |
| GermainUX runtime account | Reads and writes GermainUX indexes |
| GermainUX indexer account | Creates or manages GermainUX indexes, templates, aliases, and lifecycle configuration |
| Kibana service account | Allows Kibana to communicate with Elasticsearch |
| Human administrators | Administer Elasticsearch or Kibana through named accounts |

Apply only the cluster and index permissions required by each function.

Do not configure Kibana or GermainUX to use the `elastic` superuser permanently.

## Configure Kibana

### Connect Kibana to Elasticsearch Securely

In `kibana.yml`:

```text theme={null}
elasticsearch.hosts:
  - "https://node01.example.com:9200"

elasticsearch.ssl.certificateAuthorities:
  - "/usr/share/kibana/config/elasticsearch-ca.pem"

elasticsearch.ssl.verificationMode: "full"
```

Configure a Kibana service-account token or the approved Kibana service credentials using Kibana’s secure keystore or your container secret-management mechanism.

Do not place production passwords directly in `kibana.yml`.

### Enable HTTPS for Browsers

Configure Kibana’s public HTTPS endpoint:

```text theme={null}
server.ssl.enabled: true
server.ssl.certificate: "/usr/share/kibana/config/cert.pem"
server.ssl.key: "/usr/share/kibana/config/key.pem"
```

Mount the files read-only:

```text theme={null}
volumes:
  - /secure/kibana/kibana.yml:/usr/share/kibana/config/kibana.yml:ro
  - /secure/kibana/cert.pem:/usr/share/kibana/config/cert.pem:ro
  - /secure/kibana/key.pem:/usr/share/kibana/config/key.pem:ro
  - /secure/kibana/elasticsearch-ca.pem:/usr/share/kibana/config/elasticsearch-ca.pem:ro
```

Also configure the encryption keys required by Kibana for sessions, reporting, and encrypted saved objects.

## Restrict Network Access

Recommended firewall rules:

| Port | Source | Destination |
| - | - | - |
| `9300` | Elasticsearch nodes only | Elasticsearch nodes |
| `9200` | GermainUX Enterprise, Kibana, and approved administrators | Elasticsearch |
| `5601` | Approved user or administrator networks | Kibana |

Do not publish the Elasticsearch transport port publicly.

If ports are published by Docker, bind them to the appropriate internal interface rather than all interfaces whenever possible.

### CORS

Do not configure:

```text theme={null}
http.cors.allow-origin: "*"
```

Enable CORS only if a validated browser-based integration requires it. Restrict allowed origins to the exact approved HTTPS domains.

GermainUX server-to-server communication does not normally require unrestricted browser CORS.

## Configure GermainUX

Update GermainUX to use the secured Elasticsearch endpoint:

```text theme={null}
https://node01.example.com:9200
```

Configure:

* Elasticsearch HTTPS URL
* GermainUX runtime username
* GermainUX runtime password or approved token
* Indexer username
* Indexer password or approved token
* Trusted certificate authority
* Environment-specific index prefix

Applicable configuration keys may include:

```text theme={null}
/config/germain/application/germain.elastic.url
/config/germain/application/germain.elastic.username
/config/germain/application/germain.elastic.password
/config/germain/application/germain.indexer.url
/config/germain/application/germain.indexer.username
/config/germain/application/germain.indexer.password
```

Use the secure credential-storage method supported by your GermainUX release. Do not store production passwords in scripts, tickets, screenshots, or source control.

## Deployment Sequence

For an existing unsecured environment:

**1. Stop GermainUX Engines or pause data collection**

**2. Stop GermainUX services that write to Elasticsearch**

**3. Stop Kibana**

**4. Stop Elasticsearch according to the cluster’s controlled shutdown procedure**

**5. Back up the current configuration**

**6. Mount certificates and keystores**

**7. Enable Elasticsearch authentication and TLS**

**8. Start Elasticsearch**

**9. Validate cluster health and TLS**

**10. Create the dedicated GermainUX and Kibana identities**

**11. Configure Kibana**

**12. Start Kibana and validate HTTPS access**

**13. Update GermainUX connection and trust settings**

**14. Start GermainUX storage and core services**

**15. Validate Elasticsearch connectivity**

**16. Start remaining GermainUX services**

**17. Start GermainUX Engines**

**18. Validate ingestion, dashboards, analyses, and Session Replay**

For a multi-node cluster, use the transition procedure appropriate to the Elasticsearch version. Do not assume that all security changes can be applied through a rolling restart.

## Validate the Secured Environment

### Elasticsearch

Confirm that:

* The cluster is healthy.
* The HTTP endpoint accepts HTTPS only.
* An unauthenticated request is rejected.
* The certificate is trusted.
* Hostname verification succeeds.
* Node-to-node transport uses TLS.
* Only authorized cluster nodes can join.
* The GermainUX account has only its required permissions.

### Kibana

Confirm that:

* Kibana is available through HTTPS.
* The browser trusts the certificate.
* HTTP is disabled or redirected according to policy.
* Kibana connects to Elasticsearch securely.
* Users must authenticate.
* Unauthorized users cannot access restricted spaces or data.

### GermainUX

Confirm that:

* GermainUX Enterprise connects successfully.
* No certificate or authentication errors appear in logs.
* New monitoring facts are indexed.
* Existing dashboards return data.
* Aggregations continue to run.
* Session Replay remains available.
* GermainUX Engines continue transmitting data.
* GermainUX State shows the expected services and components.

## Rollback Plan

Prepare rollback before making any changes.

If validation fails:

**1. Stop GermainUX Engines**

**2. Stop GermainUX services**

**3. Stop Kibana**

**4. Stop Elasticsearch safely**

**5. Restore the previous Elasticsearch, Kibana, Docker Compose, and GermainUX configuration**

**6. Restore the previous truststore and secret configuration**

**7. Start Elasticsearch**

**8. Validate cluster health**

**9. Start GermainUX core services**

**10. Validate datastore connectivity**

**11. Start remaining services and Engines**

**12. Confirm data reception and dashboards**

Do not disable certificate verification or authentication merely to bypass a failed deployment. Identify and correct the certificate, hostname, trust, account, or permission problem.

## Certificate Lifecycle

For self-managed Elasticsearch and Kibana, your organization is responsible for:

* Monitoring certificate expiration
* Renewing certificates before expiration
* Updating mounted certificates
* Updating Java truststores when the issuing CA changes
* Restarting or reloading services safely
* Testing certificate rotation
* Documenting emergency renewal procedures

Review Elastic’s current guidance for [self-managed security](https://www.elastic.co/docs/deploy-manage/security/self-setup), [TLS communication](https://www.elastic.co/docs/deploy-manage/security/secure-cluster-communications), and [HTTPS setup](https://www.elastic.co/docs/deploy-manage/security/set-up-basic-security-plus-https).

For version-specific GermainUX configuration or assistance securing an existing deployment, [contact Germain](https://docs.germainux.com/main/support.md) team.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.