Securing Ethereum JSON-RPC API with Nginx and Password Protection

·

For developers building decentralized applications (DApps) on the Ethereum blockchain, securely exposing your node to the internet is a critical concern. While Go Ethereum (geth) remains one of the most widely used Ethereum clients, it does not include built-in mechanisms for securing its JSON-RPC API over HTTP. Exposing this endpoint publicly—even with restricted APIs—can leave your node vulnerable to denial-of-service attacks and unauthorized access.

This guide walks you through using Nginx as a reverse proxy with HTTP Basic Authentication to protect your Ethereum JSON-RPC API. By combining Nginx’s lightweight performance with simple password protection, you can safely expose private DApps to select users without compromising security.

Why Protect Your Ethereum Node?

DApps are typically client-side applications written in HTML, JavaScript, and CSS. They run entirely in the browser and connect to an Ethereum node via the JSON-RPC API over HTTP. Since these apps have no backend server, they rely on external nodes to read blockchain data and send transactions.

However, running geth with --http enabled and bound to a public interface opens your node to potential abuse. Even if private APIs like personal are disabled, attackers can still flood your node with requests, leading to performance degradation or crashes.

👉 Discover how secure blockchain infrastructure supports robust DApp development.

The solution? Keep your Ethereum node behind a secure gateway. Enter Nginx.

Using Nginx as a Secure Reverse Proxy

Nginx is a high-performance web server and reverse proxy widely adopted for its efficiency and reliability. One of its strengths is supporting HTTP Basic Authentication, a simple yet effective method for restricting access to web resources.

When a user tries to access your DApp or API endpoint, Nginx prompts them with a login dialog. Only those with valid credentials can proceed—adding a crucial layer of defense before any request reaches your Ethereum node.

This setup is ideal for:

Core Keywords

Installing and Configuring Nginx

We’ll use Ubuntu 14.04 or later for this tutorial, but the process is similar across most Linux distributions.

Step 1: Install Nginx and Utilities

Run the following command to install Nginx and apache2-utils, which includes the htpasswd tool for managing user credentials:

sudo apt install nginx apache2-utils

Step 2: Set Up HTTP Basic Authentication

Create a password file and add a user named demo:

sudo htpasswd -c /etc/nginx/protected.htpasswd demo

You’ll be prompted to enter and confirm a password. This file will store hashed credentials that Nginx uses to authenticate users.

Step 3: Configure Nginx as a Reverse Proxy

Edit the default site configuration located at /etc/nginx/sites-enabled/default:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    server_name demo.example.com;

    # Protect and proxy Ethereum JSON-RPC API
    location /eth {
        auth_basic "Restricted access to this site";
        auth_basic_user_file /etc/nginx/protected.htpasswd;
        proxy_pass http://localhost:8545;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Serve static DApp files with authentication
    location / {
        root /usr/share/nginx/html;
        index index.html;
        auth_basic "Restricted access to this site";
        auth_basic_user_file /etc/nginx/protected.htpasswd;
    }
}

In this configuration:

👉 Learn best practices for deploying scalable blockchain services securely.

Starting and Managing Your Geth Node

To keep your geth process running in the background, use screen:

screen
geth --http --http.addr "127.0.0.1" --http.port 8545 --http.api "eth,net,web3" --syncmode "light"

Press CTRL+A, then D to detach from the session while keeping geth running.

Ensure that:

Configuring Your DApp to Use the Protected Endpoint

Update your DApp’s web3.js provider to point to the Nginx-protected /eth route:

function getRPCURL() {
  if (window.location.href.includes("demo.example.com")) {
    return "http://demo.example.com/eth";
  } else {
    return "http://localhost:8545";
  }
}

web3.setProvider(new web3.providers.HttpProvider(getRPCURL()));

Now, when users visit your DApp, they’ll first encounter a browser-native login prompt. Upon successful authentication, the app connects to your Ethereum node through the secure proxy.

Deploying Your DApp Files

Copy your built DApp assets (HTML, JS, CSS) into Nginx’s document root:

sudo cp -r dist/* /usr/share/nginx/html/

Alternatively, automate deployment with a script using rsync:

#!/bin/bash
set -e
set -u

REMOTE="your-server-name"
npm run build

rsync -a -e "ssh" --rsync-path="sudo rsync" dist/* \
  --chown www-data:www-data $REMOTE:/usr/share/nginx/html/

This ensures files are transferred securely and ownership is correctly set for Nginx.

Restarting Nginx and Testing

Apply the new configuration:

sudo service nginx stop
sudo service nginx start

Visit http://demo.example.com in your browser. You should see:

  1. A login dialog asking for username and password.
  2. Your DApp loading successfully after authentication.
  3. Web3 interactions functioning normally.

If you encounter a 502 Bad Gateway error:

Frequently Asked Questions (FAQ)

Q: Is HTTP Basic Authentication secure enough for production?
A: It provides basic access control but should always be used with HTTPS in production. Without TLS, credentials are transmitted in base64-encoded form and can be intercepted.

Q: Can I use multiple users with different permissions?
A: Yes, htpasswd supports multiple users. However, Nginx doesn't natively support role-based access. For advanced permissions, consider adding an application-level auth layer.

Q: What happens if someone bypasses the Nginx proxy?
A: If your geth node listens only on 127.0.0.1, external access is blocked by default. This makes Nginx the only entry point—ensuring all traffic passes through authentication.

Q: Can I expose specific JSON-RPC methods only?
A: Not directly through Nginx. However, you can filter methods at the application level or use middleware tools like Express.js with custom routing logic.

Q: How do I upgrade to HTTPS for full security?
A: Use Let’s Encrypt with Certbot to obtain free SSL certificates. Update Nginx to listen on port 443 and redirect HTTP to HTTPS.

Q: Does this setup work with other Ethereum clients like OpenEthereum or Besu?
A: Yes! Any Ethereum client exposing a JSON-RPC HTTP endpoint can be protected using this same Nginx reverse proxy pattern.

👉 Explore tools that enhance Ethereum development workflows and node management.

Final Thoughts

Securing your Ethereum node doesn’t require complex infrastructure. With Nginx, HTTP Basic Authentication, and proper network configuration, you can safely expose your DApp and API to trusted users over the internet.

This approach balances simplicity, performance, and security—making it ideal for demos, internal tools, or early-stage decentralized applications. As your project scales, consider integrating TLS encryption and more granular access controls to further harden your deployment.

By taking proactive steps today, you ensure your blockchain infrastructure remains resilient against common threats—keeping your data and users safe.