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
Defguard Core has two main communication endpoints:
3
+
Defguard components exchange data over gRPC, which must be properly secured to protect sensitive information and prevent unauthorized access.
4
4
5
-
1. gRPC port for communicating with Defguard Gateways,
6
-
2. gRPC port for communicating with Defguard Core.
5
+
## Firewall rules
7
6
8
-
{% hint style="danger" %}
9
-
It is **critical** that:
7
+
Defguard components expose two ports that require firewall-level protection:
10
8
11
-
1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes.
12
-
2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core.
13
-
3. If you want an additional layer of security, then you should create a **custom SSL Certificate Authority (CA)**, and provide Core, Proxy and Gateway Certificates from that CA so **any other connections to the gRPC services will not be accepted.**
14
-
4. Even if you have secured the network ports/firewall and do not want to create a custom SSL CA, please secure gRPC traffic with SSL and a reverse proxy.
15
-
{% endhint %}
9
+
* Defguard Core exposes a gRPC port for communication with Defguard Gateways.
10
+
* Defguard Proxy exposes a gRPC port for communication with Defguard Core.
11
+
12
+
Limit access to gRPC ports:
13
+
14
+
* Allow Core’s gRPC port only from Gateway IPs.
15
+
* Allow Proxy’s gRPC port only from Core’s IP.
16
+
17
+
## SSL encryption
18
+
19
+
Even if you already use [SSL on a reverse proxy](reverse-proxy-configuration-using-nginx.md#obtaining-ssl-certificates), this only protects external traffic. Internal gRPC connections between Proxy, Core, and Gateways occur behind the proxy and must also be encrypted and authenticated. These connections carry sensitive operational data and should never be left unprotected.
20
+
21
+
You can **choose one** of two approaches:
22
+
23
+
*[Trusted CA certificates](grpc-ssl-communication.md#trusted-ca-certificates) (simple) – use certificates issued by a recognized Certificate Authority (e.g., Let’s Encrypt). This ensures encrypted traffic and verifies the identity of each component. This approach assumes you're already using [reverse proxy with SSL termination](reverse-proxy-configuration-using-nginx.md#obtaining-ssl-certificates) for Defguard Core or Defguard Proxy.
24
+
*[Custom internal CA](grpc-ssl-communication.md#custom-internal-ca) (recommended) – create your own Certificate Authority and issue certificates for Core, Proxy, and Gateway. This enables mutual TLS (mTLS), so only trusted Defguard components can communicate.
25
+
26
+
Choose one of these options based on your environment: trusted CA for simplicity, or a custom CA for full Zero Trust mutual authentication.
27
+
28
+
### Trusted CA certificates
29
+
30
+
If you followed our [guide on configuring SSL for reverse proxy](reverse-proxy-configuration-using-nginx.md#obtaining-ssl-certificates) your certificates should be located in the following path `/etc/letsencrypt/live/domain.name/`. Use the PEM-formatted CA certificate for configuring Defguard components.  
31
+
32
+
#### Configure Defguard Core
33
+
34
+
Add path to CA certificate file using command line arguments:
To secure not only with firewall communication between all Defguard gRPC components, a custom SSL chain of certificates should be used. This way the trust will be ensured on the Transport Layer Security (TLS) level.
It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one under which a service is being hosted.
55
+
Add path to CA certificate file using command line arguments:
It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one **under which a service is being hosted**.
78
+
{% endhint %}
79
+
80
+
#### Generate certificates
24
81
25
82
To quickly generate a set of SSL certificates using [OpenSSL](https://openssl-library.org) or [LibreSSL](https://www.libressl.org), use the following:
26
83
@@ -52,19 +109,25 @@ To display certificate file contents:
52
109
openssl x509 -noout -text -in core.crt
53
110
```
54
111
55
-
### Defguard configuration
56
-
57
-
#### Defguard Core
112
+
#### Configure Defguard Core
58
113
59
-
Using command line arguments
114
+
Add paths to certificate files using command line arguments:
Add paths to certificate files using command line arguments:
79
142
80
143
```sh
81
144
defguard-proxy --grpc-cert path/to/proxy.crt \
82
145
--grpc-key path/to/proxy.key
83
146
```
84
147
85
-
Using environment variables
148
+
or using the service's configuration file:
149
+
150
+
```toml
151
+
grpc_cert = "path/to/core.crt"
152
+
grpc_key = "path/to/core.key"
153
+
```
154
+
155
+
or using environment variables:
86
156
87
157
```sh
88
158
env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \
89
159
DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key
90
160
defguard-proxy
91
161
```
92
162
93
-
### Defguard Gateway
163
+
#### Configure Defguard Gateway
94
164
95
-
Using command line arguments
165
+
Add paths to certificate files using command line arguments:
96
166
97
167
```sh
98
168
defguard-gateway --grpc-ca path/to/ca.crt
99
169
```
100
170
101
-
Using environment variables
102
-
103
-
```sh
104
-
env DEFGUARD_GRPC_CA=path/to/ca.crt \
105
-
defguard-gateway
106
-
```
107
-
108
-
Using configuration file
171
+
or using the service's configuration file:
109
172
110
173
```toml
111
174
grpc_ca = "path/to/ca.crt"
112
175
```
113
176
114
-
## Trusted CA (eg. Let'sEncrypt or others)
177
+
or using environment variables:
115
178
116
-
Often (like in the standalone package based installation tutorial) gRPC communication can be secured by a reverse proxy (NGINX, Caddy, Traefik, etc.) that handles SSL termination. It's common to use typical trusted CA (that is used for typical HTTPS traffic) like Let'sEncrypt or others.
117
-
118
-
{% hint style="danger" %}
119
-
While this secures the transport layer and encrypts communication between Defguard components - it does not provide authorization between gRPC components like Custom CA does.
179
+
```sh
180
+
env DEFGUARD_GRPC_CA=path/to/ca.crt \
181
+
defguard-gateway
182
+
```
120
183
121
-
Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall.
122
-
{% endhint %}
123
184
124
-
If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for:
125
185
126
-
* Defguard Gateway – in _gateway.toml_ add path to CA certificate file (in PEM format); for example, when using standard Let'sEncrypt installation ([Certbot](https://certbot.eff.org)), you configure the CA path like this:
Copy file name to clipboardExpand all lines: deployment-strategies/reverse-proxy-configuration-using-nginx.md
+53-25Lines changed: 53 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,55 +1,84 @@
1
-
# Reverse Proxy configuration using NGINX
1
+
# Reverse Proxy configuration using Nginx
2
2
3
3
## Introduction
4
4
5
5
This guide explains how to configure [NGINX](https://nginx.org/) as a reverse proxy for Defguard's components (Core and Proxy). The reverse proxy acts as an intermediary between users and Defguard services, handling HTTPS requests, routing internal gRPC communication, and ensuring encrypted connections between all components.
6
6
7
7
To provide HTTPS encryption, this guide also uses [Certbot](https://certbot.eff.org/), a free, open-source tool from the [Let’s Encrypt](https://letsencrypt.org/) project. Certbot automatically issues and renews SSL/TLS certificates, allowing you to secure your Defguard domains without manual certificate management.
8
8
9
-
### Installing NGINX and Certbot
9
+
{% hint style="info" %}
10
+
We assume in this guide that you run your Core and Proxy services on separate servers, and you run Certbot and Nginx on each one of them.
11
+
{% endhint %}
10
12
11
-
To install and prepare NGINX with Let’s Encrypt certificates:
13
+
## Installing Nginx and Certbot
14
+
15
+
Run the followign command to install Nginx and Certbot.
12
16
13
17
```bash
14
18
apt install nginx certbot
15
-
systemctl enable nginx.service
16
-
systemctl start nginx.service
17
19
```
18
20
19
-
Disable the default configuration to avoid conflicts:
21
+
Disable the default Nginx configuration to avoid conflicts:
20
22
21
23
```bash
22
24
unlink /etc/nginx/sites-enabled/default
23
25
```
24
26
25
-
### Obtaining SSL Certificates
27
+
## Obtaining SSL certificates
28
+
29
+
Use Certbot to generate SSL certificates. 
30
+
31
+
For each service (Core, Proxy), run the following command on the server that your domain’s DNS records resolve to. Ensure that inbound traffic on port 80 is allowed by the firewall and that no other process is using this port.
32
+
33
+
{% hint style="info" %}
34
+
Certbot verifies domain ownership using the HTTP-01 challenge, where it temporarily serves a validation file over port 80 for the exact domain you are requesting a certificate for. 
35
+
36
+
If the request fails with a timeout or connection error, Let’s Encrypt could not reach this temporary server. This usually means the DNS record for that domain does not point to the correct public IP of the machine running Certbot, port 80 is blocked (firewall or Security Group), an IPv6 (AAAA) record is published but not supported on the server, or another service is already using port 80. 
26
37
27
-
Before configuring NGINX, issue valid SSL certificates for your domains.\
28
-
In this example we use:
38
+
Ensure the domain’s DNS resolves to this server’s public IP, inbound port 80 is open, and no other service is binding the port before trying again.
39
+
{% endhint %}
29
40
30
-
* Core: **my-server.defguard.net**
31
-
* Enrollment (Proxy): **enroll.defguard.net**
41
+
### Obtaining SSL certificate for Core service
32
42
33
-
Generate certificates with Certbot:
43
+
Use the following command to generate certificate with Certbot. Replace the example domain for the Core service (my-server.defguard.net) with your own.
If you use this simple setup and run all services on one server, you can use [NGINX access restrictions](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-tcp/) for securing core and allowing to access the _my-server.defguard.net_ only to selected networks - blocking the direct access from the Internet.
0 commit comments