When an NGINX reverse proxy encounters a backend server with an invalid or self-signed SSL certificate, clients receive browser security warnings that block access. To resolve this while maintaining the reverse proxy architecture, you must configure NGINX to ignore upstream certificate validation errors by setting
proxy_ssl_verify off;. This directive allows NGINX to establish a secure tunnel to the backend without validating its identity, ensuring seamless connectivity for end-users who are served valid certificates from the proxy itself.
Understanding the Connection Flow
In a standard reverse proxy setup, the client connects to NGINX over HTTPS using a valid certificate issued by a trusted Certificate Authority (CA). NGINX then initiates a separate connection to the backend application server. If the backend uses a self-signed certificate, a wildcard certificate not matching the hostname, or an expired certificate, the TLS handshake between NGINX and the backend fails strict verification checks. By default, NGINX acts as a strict validator and will reject the upstream connection if the certificate chain is incomplete or untrusted, resulting in HTTP 502 Bad Gateway errors or SSL handshake failures logged in the NGINX error log.
The core issue arises because NGINX treats the backend connection independently of the client connection. Even if the client trusts NGINX's certificate, they do not inherently trust the backend's certificate. Therefore, the proxy must be explicitly instructed to relax its security requirements regarding the upstream server's identity. This is particularly common in internal networks, development environments, or when managing legacy applications that cannot easily obtain public CA-signed certificates.
Configuring Upstream SSL Verification
To fix the invalid backend certificate issue, you need to modify the
server block within your NGINX configuration file. The specific directive required is
proxy_ssl_verify. Setting this to
off disables the verification of the peer certificate during the SSL handshake with the upstream server.
Add the following line inside the
location block or the
server block where your reverse proxy rules are defined:
server {
listen 443 ssl;
server_name example.com;
# Existing SSL configuration for the client-facing side
ssl_certificate /etc/ssl/certs/example.crt;
ssl_certificate_key /etc/ssl/private/example.key;
location / {
proxy_pass https://backend-server-ip;
# Disable verification of the upstream backend certificate
proxy_ssl_verify off;
# Optional: Specify the backend hostname if it differs from the IP
# proxy_ssl_server_name on;
}
}
It is crucial to understand that
proxy_ssl_verify off only affects the connection between NGINX and the backend. The connection between the user's browser and NGINX remains fully secured and verified. This means that while NGINX ignores the backend's certificate validity, the data transmitted between the client and NGINX is still encrypted and authenticated.
If your backend server presents a certificate with a hostname that does not match the address used in
proxy_pass, you may also need to enable
proxy_ssl_server_name on;. This ensures that the SNI (Server Name Indication) extension is sent correctly, although it does not bypass the verification failure if the certificate is fundamentally invalid.
Security Implications and Best Practices
Disabling upstream SSL verification introduces a man-in-the-middle (MITM) risk between NGINX and the backend. An attacker on the same network segment as the backend could potentially intercept or modify traffic if they can spoof the backend's IP address. However, in most reverse proxy scenarios, the backend resides in a private network or a controlled environment where such risks are mitigated by network segmentation.
For production environments where security is paramount, the recommended approach is to install a valid, CA-signed certificate on the backend server. Tools like Let's Encrypt can automate this process even for internal services if proper DNS records are configured. Alternatively, you can create a private PKI (Public Key Infrastructure) and distribute the root CA certificate to all NGINX instances, allowing them to verify the backend's self-signed certificate properly.
If you are configuring similar setups for other applications, you might find our guide on
How to disable SSL checking on Nginx? helpful for understanding broader contexts of SSL handling. Additionally, for specific use cases like Paperless-ngx, we discuss
Configuring SSL Passthrough with Certificates on Nginx Reverse Proxy for Paperless-ngx, which offers an alternative architectural approach.
Diagnostics and Troubleshooting
After applying the configuration change, always test the syntax before reloading NGINX. Run the following command to ensure there are no syntax errors:
sudo nginx -t
If the test passes, reload the service:
sudo systemctl reload nginx
Monitor the error logs to confirm the issue is resolved:
sudo tail -f /var/log/nginx/error.log
You should no longer see errors related to "SSL_do_handshake() failed" or "certificate verify failed." Instead, you should see successful proxy connections. If issues persist, verify that the backend server is actually listening on port 443 and that firewall rules allow traffic between the NGINX host and the backend.
Frequently Asked Questions
Does disabling proxy_ssl_verify expose my users to attacks?
No, it does not directly expose users to attacks because the client-to-proxy connection remains fully encrypted and verified. The risk is limited to the potential interception of data between the proxy and the backend, which is usually mitigated by network isolation.
Can I use a custom CA certificate instead of disabling verification?
Yes, you can specify a custom CA bundle using
proxy_ssl_trusted_certificate and set
proxy_ssl_verify on;. This allows NGINX to verify the backend's self-signed certificate against your internal root CA, providing security without disabling checks entirely.
Why am I still getting SSL errors after adding proxy_ssl_verify off?
Ensure that you have reloaded NGINX after making changes. Also, check if the backend server is responding with a different certificate than expected, or if there are intermediate certificate issues that require
proxy_ssl_server_name on; to resolve SNI mismatches.
Is this method suitable for public-facing backends?
It is generally not recommended for public-facing backends due to the loss of mutual authentication. For public services, always use valid, publicly trusted certificates to prevent man-in-the-middle attacks between the proxy and the origin server.
How do I verify the backend certificate details manually?
You can use OpenSSL to inspect the backend certificate directly from the NGINX server using the command:
openssl s_client -connect backend-ip:443 -servername backend-hostname. This helps identify expiration dates, subject names, and issuer information to diagnose certificate validity issues.