defguard
  • Introduction
  • User documentation (help)
    • Configuring VPN
      • Defguard Desktop Client
        • Update instance
      • Other WireGuard® Clients
        • Configuring a device for new VPN Location manually
    • Password change / Reset
    • Enrollment & Onboarding
      • With internal Defguard SSO
      • With external SSO (Google/Microsoft/Custom)
    • Setting up 2FA/MFA
    • Desktop Client
    • CLI Client
  • Admin & features
    • Deploying your instance
      • One-line install script
      • Standalone package based installation
      • Docker images and tags
      • Docker Compose
      • Kubernetes
      • Upgrading
      • Gateway
        • Running gateway on MikroTik routers
      • Securing gRPC communication
      • OpenID RSA key
      • Configuration
      • Pre-production and development releases
      • High Availability and Failover
      • Health check
    • Features & configuration
      • Zero-Trust VPN with 2FA/MFA
        • Create/manage VPN Location
        • Network overview
        • Executing custom gateway commands
        • Multi-Factor Authentication (MFA/2FA)
          • MFA Architecture
        • Remote desktop client configuration
        • DNS and domains
      • Remote user enrollment
        • User onboarding after enrollment
      • SSO (OpenID Connect)
        • Portainer
        • Grafana setup
        • Proxmox
        • Matrix / Synapse
        • Django
        • MinIO
        • Vault
      • SMTP for email notifications
      • YubiKey Provisioning
      • Webhooks
      • Forward auth
      • SSH Authentication
      • Network devices
      • Gateway notifications
      • New version notifications
  • Troubleshooting Guide
    • Sending support information
    • Client Windows installer exit codes
    • Client "All traffic" connection issues
    • WebAuthn security keys
  • Enterprise Features
    • License
    • Enteprise features
      • Automatic (real time) desktop client configuration & sync
      • External OpenID providers
        • Google
        • Microsoft
        • Zitadel
        • Keycloak
        • JumpCloud
        • Okta
        • Custom
      • External OIDC secure enrollment
      • VPN & Client behavior customization
      • REST API
      • Access Control List
        • ACL Aliases
      • LDAP and Active Directory integration
        • Configuration
        • Settings table
        • Two-way LDAP and Active Directory synchronization
  • Tutorials
    • Step by step setting up a VPN server
      • Adding additional VPN locations
  • In depth
    • Roadmap
    • Architecture
      • How do VPN statistics work
      • Security concepts
  • For Developers
    • Contributing
    • Environment setup
    • Translations (core/web)
      • Switching language
      • Adding translations
  • Translations (client)
    • Adding translations
  • Contact us
    • Community & Support
Powered by GitBook
On this page
  • Custom SSL CA and certificates
  • Quick setup
  • Defguard configuration
  • Defguard Gateway
  • Trusted CA (eg. Let'sEncrypt or others)

Was this helpful?

Edit on GitHub
  1. Admin & features
  2. Deploying your instance

Securing gRPC communication

PreviousRunning gateway on MikroTik routersNextOpenID RSA key

Last updated 7 months ago

Was this helpful?

Defguard Core has two main communication endpoints:

  1. gRPC port for communicating with Defguard Gateways,

  2. gRPC port for communicating with Defguard Core.

It is critical that:

  1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes.

  2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core.

  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.

  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.

Custom SSL CA and certificates

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.

Quick setup

To quickly generate a set of SSL certificates using or , use the following:

  • Generate Certificate Authority (CA) cerfiticate and key for domain example.local

openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt
  • Generate private key and Certificate Signing Request (CSR)

openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local
  • Generate certificate by signing the CSR, valid for 365 days

openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy

Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly.

To display certificate file contents:

openssl x509 -noout -text -in core.crt

Defguard configuration

Defguard Core

Using command line arguments

defguard --grpc-cert path/to/core.crt \
         --grpc-key path/to/core.key \
         --proxy-grpc-ca path/to/ca.crt

Using environment variables

env DEFGUARD_GRPC_CERT=path/to/core.crt \
    DEFGUARD_GRPC_KEY=path/to/core.key \
    DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \
    defguard

Defguard Proxy

Using command line arguments

defguard-proxy --grpc-cert path/to/proxy.crt \
               --grpc-key path/to/proxy.key

Using environment variables

env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \
    DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key
    defguard-proxy

Defguard Gateway

Using command line arguments

defguard-gateway --grpc-ca path/to/ca.crt

Using environment variables

env DEFGUARD_GRPC_CA=path/to/ca.crt \
    defguard-gateway

Using configuration file

grpc_ca = "path/to/ca.crt"

Trusted CA (eg. Let'sEncrypt or others)

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.

While this secures the transport layer and encrypts communication between defguard components - it does not provide authorization between gRPC components like Custom CA does.

Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall.

If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for:

    • grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem"

  • Defguard Core – similarily, you need to configure Proxy CA certificate file using DEFGUARD_PROXY_GRPC_CA environment variable:

    • DEFGUARD_PROXY_GRPC_CA: /etc/letsencrypt/live/domain.name/chain.pem

Defguard Gateway – in gateway.toml add path to CA certificate file (in PEM format); for example when using standard Let'sEncrypt installation (), you configure the CA path like this:

OpenSSL
LibreSSL
Certbot