Skip to content

Commit bf041f7

Browse files
RomuDeuxfoisRomuDeuxfois
authored
[docs]: add certificate validation guide for server-side enforcement (#260)
1 parent b32c659 commit bf041f7

2 files changed

Lines changed: 131 additions & 3 deletions

File tree

‎docs/deployment/certificate-validation.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Certificate validation
2+
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+
5+
## What is this?
6+
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+
9+
## Why does it matter?
10+
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.
14+
15+
## Outgoing connections (OpenAEV as client)
16+
17+
### Strict validation (default)
18+
19+
By default, OpenAEV validates all outgoing TLS certificates against the JVM's default trust store (`cacerts`). No configuration is needed.
20+
21+
| Parameter | Environment variable | Default | Description |
22+
|:--|:--|:--|:--|
23+
| `openaev.unsecured-certificate` | `OPENAEV_UNSECURED-CERTIFICATE` | `false` | Reject untrusted SSL certificates |
24+
25+
⚠️ **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.
26+
27+
### Allow self-signed certificates (dev/test only)
28+
29+
For development or air-gapped environments with self-signed certificates, disable strict validation:
30+
31+
```yaml
32+
services:
33+
openaev:
34+
image: openaev/platform:latest
35+
environment:
36+
- OPENAEV_UNSECURED-CERTIFICATE=true
37+
```
38+
39+
⚠️ **Warning** — Use this only in controlled, non-production environments.
40+
41+
### Add custom trusted certificates (recommended)
42+
43+
Instead of disabling validation, add your internal CA or self-signed certificates to the OpenAEV trust store:
44+
45+
| Parameter | Environment variable | Default | Description |
46+
|:--|:--|:--|:--|
47+
| `openaev.extra-trusted-certs-dir` | `OPENAEV_EXTRA-TRUSTED-CERTS-DIR` | — | Directory containing additional trusted PEM certificates |
48+
49+
**Requirements:**
50+
51+
- Certificate files must be in **PEM format** (`.pem`) or **DER-encoded X.509** format.
52+
- The directory must be readable by the OpenAEV process.
53+
54+
### Example
55+
56+
You have an internal CA that signs certificates for your CrowdStrike and Tanium integrations.
57+
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:
61+
62+
```yaml
63+
services:
64+
openaev:
65+
image: openaev/platform:latest
66+
environment:
67+
- OPENAEV_EXTRA-TRUSTED-CERTS-DIR=/opt/openaev/certs
68+
volumes:
69+
- ./my-custom-certs:/opt/openaev/certs:ro
70+
```
71+
72+
OpenAEV now trusts your internal CA **while keeping strict validation** for everything else.
73+
74+
💡 **Tip** — This is the recommended approach for production environments with internal PKI.
75+
76+
## Incoming connections (TLS termination)
77+
78+
OpenAEV can terminate TLS directly using Spring Boot's built-in SSL support, without a reverse proxy.
79+
80+
| Parameter | Environment variable | Default | Description |
81+
|:--|:--|:--|:--|
82+
| `server.ssl.enabled` | `SERVER_SSL_ENABLED` | `false` | Enable SSL on the server |
83+
| `server.ssl.key-store-type` | `SERVER_SSL_KEY-STORE-TYPE` | `PKCS12` | Keystore type |
84+
| `server.ssl.key-store` | `SERVER_SSL_KEY-STORE` | `classpath:localhost.p12` | Keystore path |
85+
| `server.ssl.key-store-password` | `SERVER_SSL_KEY-STORE-PASSWORD` | `admin` | Keystore password |
86+
| `server.ssl.key-alias` | `SERVER_SSL_KEY-ALIAS` | `localhost` | Key alias in keystore |
87+
88+
### Example
89+
90+
```yaml
91+
services:
92+
openaev:
93+
image: openaev/platform:latest
94+
environment:
95+
- SERVER_SSL_ENABLED=true
96+
- SERVER_SSL_KEY-STORE-TYPE=PKCS12
97+
- SERVER_SSL_KEY-STORE=/opt/openaev/keystore.p12
98+
- SERVER_SSL_KEY-STORE-PASSWORD=my-secure-password
99+
- SERVER_SSL_KEY-ALIAS=openaev
100+
- OPENAEV_COOKIE-SECURE=true
101+
volumes:
102+
- ./keystore.p12:/opt/openaev/keystore.p12:ro
103+
```
104+
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+
107+
## Proxy support
108+
109+
If OpenAEV connects to external services through a proxy, enable proxy support:
110+
111+
| Parameter | Environment variable | Default | Description |
112+
|:--|:--|:--|:--|
113+
| `openaev.with-proxy` | `OPENAEV_WITH-PROXY` | `false` | Enable proxy environment support |
114+
115+
When enabled, OpenAEV respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.
116+
117+
## Quick reference
118+
119+
| Scenario | Configuration |
120+
|:--|:--|
121+
| Production with public CA-signed certificates | Default (no changes needed) |
122+
| Internal CA or self-signed certs for integrations | `openaev.extra-trusted-certs-dir` → your PEM directory |
123+
| Development / testing | `openaev.unsecured-certificate=true` (temporary only) |
124+
| TLS termination on OpenAEV | `server.ssl.enabled=true` + keystore config |
125+
| TLS termination on reverse proxy | `server.ssl.enabled=false` + `openaev.cookie-secure=true` |
126+
127+
## What's next?
128+
129+
- [Configuration reference](../configuration.md) — Full list of OpenAEV platform parameters.
130+
- [Deployment overview](../overview.md) — Architecture and deployment options.

‎mkdocs.yml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ nav:
116116
- Overview: deployment/platform/overview.md
117117
- Installation: deployment/installation.md
118118
- Configuration: deployment/configuration.md
119+
- Certificate validation: deployment/certificate-validation.md
119120
- Authentication: deployment/authentication.md
120121
- Upgrade: deployment/upgrade.md
121122
- Ecosystem:
@@ -217,6 +218,3 @@ nav:
217218
- Injectors: development/injectors.md
218219
- REST API: development/api-usage.md
219220
- Best Practices: development/translations.md
220-
221-
222-

0 commit comments

Comments
 (0)