You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page explains how OpenAEV handles TLS/SSL certificate validation on the server side, and how administrators can enforce or relax certificate checks depending on their environment.
3
+
OpenAEV enforces TLS/SSL certificate validation on the server side by default. This page explains how to configure certificate trust for outgoing and incoming connections.
4
4
5
-
## Overview
5
+
## What is this?
6
6
7
-
By default, OpenAEV **enforces certificate validation** for all outgoing HTTPS connections (to injectors, collectors, external APIs, etc.). This means that the server will reject connections to endpoints presenting invalid, expired, or untrusted certificates.
7
+
Certificate validation ensures that OpenAEV only communicates with trusted endpoints. When OpenAEV connects to injectors, collectors, or external APIs over HTTPS, it verifies that the remote certificate is valid, not expired, and issued by a trusted Certificate Authority (CA).
8
8
9
-
OpenAEV provides several configuration options to control this behavior:
9
+
## Why does it matter?
10
10
11
-
-**Strict mode (default):**Only connections with valid, trusted certificates are allowed.
12
-
-**Unsecured mode:**Self-signed or untrusted certificates are accepted (useful for development or air-gapped environments).
13
-
-**Custom trust store:**Add your own CA or self-signed certificates to the trust chain without disabling validation entirely.
11
+
-**Security**— Prevents man-in-the-middle (MITM) attacks on all outgoing connections.
12
+
-**Compliance**— Many security frameworks require strict TLS validation in production.
13
+
-**Flexibility**— OpenAEV supports custom trust stores, so you can trust internal CAs without disabling validation.
⚠️ **Warning** — Keep this set to `false` in production. Setting it to `true` disables certificate chain validation for **all** outgoing connections and exposes the platform to MITM attacks.
In production environments, `openaev.unsecured-certificate` should **always** be set to `false` (the default). Enabling unsecured certificates bypasses critical security checks and exposes the platform to man-in-the-middle attacks.
29
+
For development or air-gapped environments with self-signed certificates, disable strict validation:
30
30
31
-
### Allow self-signed or untrusted certificates
32
-
33
-
If your environment uses self-signed certificates (e.g., internal PKI, development setups, air-gapped networks), you can disable strict validation:
31
+
```yaml
32
+
services:
33
+
openaev:
34
+
image: openaev/platform:latest
35
+
environment:
36
+
- OPENAEV_UNSECURED-CERTIFICATE=true
37
+
```
34
38
35
-
| Parameter | Environment variable | Value | Description |
⚠️ **Warning** — Use this only in controlled, non-production environments.
38
40
39
-
!!! danger "Security risk"
41
+
### Add custom trusted certificates (recommended)
40
42
41
-
Setting `openaev.unsecured-certificate` to `true` disables certificate chain validation for **all** outgoing connections. This should only be used in controlled, non-production environments.
43
+
Instead of disabling validation, add your internal CA or self-signed certificates to the OpenAEV trust store:
Instead of disabling validation entirely, you can add your own trusted certificates (e.g., internal CA, self-signed certs for third-party integrations like CrowdStrike, Tanium, SentinelOne) to the OpenAEV trust store:
- Certificate files must be in **PEM format** (`.pem`) or **DER-encoded X.509** format.
52
+
- The directory must be readable by the OpenAEV process.
50
53
51
-
**Requirements:**
54
+
### Example
52
55
53
-
- Certificate files must be in **PEM-armoured format** (`.pem` extension) or **DER-encoded X509** format.
54
-
- The directory must be accessible by the OpenAEV process.
56
+
You have an internal CA that signs certificates for your CrowdStrike and Tanium integrations.
55
57
56
-
**Example with Docker Compose:**
58
+
1. Export your internal CA certificate as `internal-ca.pem`.
59
+
2. Place it in a `./my-custom-certs/` directory on the host.
60
+
3. Mount it into the container:
57
61
58
62
```yaml
59
63
services:
@@ -65,25 +69,23 @@ services:
65
69
- ./my-custom-certs:/opt/openaev/certs:ro
66
70
```
67
71
68
-
Place your `.pem` certificate files in the `./my-custom-certs` directory on the host.
69
-
70
-
!!! tip "Best practice"
72
+
OpenAEV now trusts your internal CA **while keeping strict validation** for everything else.
71
73
72
-
Using `openaev.extra-trusted-certs-dir` is the **recommended approach** for environments with internal CAs or self-signed certificates. It allows you to maintain strict certificate validation while trusting specific certificates.
74
+
💡 **Tip** — This is the recommended approach for production environments with internal PKI.
73
75
74
-
## Server-side SSL/TLS (incoming connections)
76
+
## Incoming connections (TLS termination)
75
77
76
-
OpenAEV can also terminate TLS directly (without a reverse proxy) using the built-in Spring Boot SSL support:
78
+
OpenAEV can terminate TLS directly using Spring Boot's built-in SSL support, without a reverse proxy.
| `server.ssl.key-alias` | `SERVER_SSL_KEY-ALIAS` | `localhost` | Key alias in keystore |
85
87
86
-
**Example configuration:**
88
+
### Example
87
89
88
90
```yaml
89
91
services:
@@ -100,26 +102,29 @@ services:
100
102
- ./keystore.p12:/opt/openaev/keystore.p12:ro
101
103
```
102
104
103
-
!!! note "Reverse proxy"
104
-
105
-
Most production deployments terminate TLS at a reverse proxy (Nginx, Traefik, HAProxy) rather than on the OpenAEV server itself. In that case, leave `server.ssl.enabled` as `false` and configure TLS on your reverse proxy. Make sure to set `openaev.cookie-secure=true` if the end-user connection is over HTTPS.
105
+
💡 **Tip** — Most production deployments terminate TLS at a reverse proxy (Nginx, Traefik, HAProxy). In that case, leave `server.ssl.enabled=false` and set `openaev.cookie-secure=true` if end-users connect over HTTPS.
106
106
107
107
## Proxy support
108
108
109
109
If OpenAEV connects to external services through a proxy, enable proxy support:
0 commit comments