Skip to content

Commit e6ccf51

Browse files
RomuDeuxfoisRomuDeuxfois
committed
docs: add certificate validation guide for server-side enforcement
1 parent 7c10be0 commit e6ccf51

1 file changed

Lines changed: 125 additions & 0 deletions

File tree

‎docs/deployment/certificate-validation.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Certificate validation
2+
3+
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.
4+
5+
## Overview
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.
8+
9+
OpenAEV provides several configuration options to control this behavior:
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.
14+
15+
## Configuration parameters
16+
17+
### Enforce strict certificate validation (default)
18+
19+
By default, no additional configuration is needed. OpenAEV validates all TLS certificates against the JVM's default trust store (Java `cacerts`).
20+
21+
To explicitly ensure strict validation is enforced, verify the following:
22+
23+
| Parameter | Environment variable | Value | Description |
24+
|:------------------------------|:--------------------------------|:--------|:-----------------------------------------------------|
25+
| openaev.unsecured-certificate | OPENAEV_UNSECURED-CERTIFICATE | `false` | Reject self-signed or untrusted SSL certificates |
26+
27+
!!! warning "Production recommendation"
28+
29+
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.
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:
34+
35+
| Parameter | Environment variable | Value | Description |
36+
|:------------------------------|:--------------------------------|:-------|:---------------------------------------------------------|
37+
| openaev.unsecured-certificate | OPENAEV_UNSECURED-CERTIFICATE | `true` | Accept self-signed or untrusted SSL certificates |
38+
39+
!!! danger "Security risk"
40+
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.
42+
43+
### Add custom trusted certificates (recommended approach)
44+
45+
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:
46+
47+
| Parameter | Environment variable | Default | Description |
48+
|:--------------------------------|:----------------------------------|:--------|:---------------------------------------------------------------|
49+
| openaev.extra-trusted-certs-dir | OPENAEV_EXTRA-TRUSTED-CERTS-DIR | | Local directory containing additional trusted PEM certificates |
50+
51+
**Requirements:**
52+
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.
55+
56+
**Example with Docker Compose:**
57+
58+
```yaml
59+
services:
60+
openaev:
61+
image: openaev/platform:latest
62+
environment:
63+
- OPENAEV_EXTRA-TRUSTED-CERTS-DIR=/opt/openaev/certs
64+
volumes:
65+
- ./my-custom-certs:/opt/openaev/certs:ro
66+
```
67+
68+
Place your `.pem` certificate files in the `./my-custom-certs` directory on the host.
69+
70+
!!! tip "Best practice"
71+
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.
73+
74+
## Server-side SSL/TLS (incoming connections)
75+
76+
OpenAEV can also terminate TLS directly (without a reverse proxy) using the built-in Spring Boot SSL support:
77+
78+
| Parameter | Environment variable | Default value | Description |
79+
|:-----------------------------|:-----------------------------|:----------------------|:-------------------------|
80+
| server.ssl.enabled | SERVER_SSL_ENABLED | `false` | Enable SSL on the server |
81+
| server.ssl.key-store-type | SERVER_SSL_KEY-STORE-TYPE | PKCS12 | Keystore type |
82+
| server.ssl.key-store | SERVER_SSL_KEY-STORE | classpath:localhost.p12 | Keystore path |
83+
| server.ssl.key-store-password| SERVER_SSL_KEY-STORE-PASSWORD| admin | Keystore password |
84+
| server.ssl.key-alias | SERVER_SSL_KEY-ALIAS | localhost | Key alias in keystore |
85+
86+
**Example configuration:**
87+
88+
```yaml
89+
services:
90+
openaev:
91+
image: openaev/platform:latest
92+
environment:
93+
- SERVER_SSL_ENABLED=true
94+
- SERVER_SSL_KEY-STORE-TYPE=PKCS12
95+
- SERVER_SSL_KEY-STORE=/opt/openaev/keystore.p12
96+
- SERVER_SSL_KEY-STORE-PASSWORD=my-secure-password
97+
- SERVER_SSL_KEY-ALIAS=openaev
98+
- OPENAEV_COOKIE-SECURE=true
99+
volumes:
100+
- ./keystore.p12:/opt/openaev/keystore.p12:ro
101+
```
102+
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.
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+
## Summary: which option to choose?
118+
119+
| Scenario | Recommended configuration |
120+
|:--------------------------------------------------|:---------------------------------------------------------------------------------|
121+
| Production with public CA-signed certificates | Default settings (no changes needed) |
122+
| Internal CA or self-signed certs for integrations | `openaev.extra-trusted-certs-dir` pointing to your PEM certificates directory |
123+
| Development / testing environment | `openaev.unsecured-certificate=true` (temporary only) |
124+
| TLS termination on OpenAEV server | `server.ssl.enabled=true` + keystore configuration |
125+
| TLS termination on reverse proxy | `server.ssl.enabled=false` + `openaev.cookie-secure=true` |

0 commit comments

Comments
 (0)