How to Use Nginx Password Protection for Ethereum JSON-RPC API Security

This comprehensive guide explains how to configure Nginx as a reverse proxy with HTTP Basic Authentication to secure your Ethereum JSON-RPC API endpoints. Following these steps will help protect your node from unauthorized access while maintaining accessibility for trusted users.

Why Secure Your Ethereum JSON-RPC API?

Ethereum nodes running software like Go Ethereum (geth), Parity, or others expose JSON-RPC APIs that decentralized applications (DApps) use to interact with the blockchain. However, leaving these APIs publicly accessible poses significant risks:

• Denial-of-Service (DoS) Attacks: Open endpoints can be exploited to overwhelm your node.
• Unauthorized Access: Sensitive blockchain data or wallet operations could be compromised.
• Resource Abuse: Attackers might misuse your node's resources for mining or spam transactions.

HTTP Basic Authentication adds a simple yet effective layer of security by requiring username/password credentials for API access.

Step-by-Step Nginx Configuration

1. Install Nginx and Dependencies

On Ubuntu/Debian systems:

sudo apt update
sudo apt install nginx apache2-utils

The apache2-utils package includes htpasswd, a tool for creating password files.

2. Create Password File

Generate a password file (replace username with your chosen username):

sudo htpasswd -c /etc/nginx/.htpasswd username

You’ll be prompted to set a password. To add more users later, omit the -c flag:

sudo htpasswd /etc/nginx/.htpasswd another_username

3. Configure Nginx as a Reverse Proxy

Edit the default Nginx configuration (/etc/nginx/sites-available/default):

server {
    listen 80;
    server_name yourdomain.com;

    # Password-protected Ethereum JSON-RPC endpoint
    location /eth {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://localhost:8545;  # Forward to geth/Parity
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Serve static DApp files (optional)
    location / {
        root /var/www/html;
        index index.html;
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

Key Directives:

• auth_basic: Enables HTTP Basic Auth with a custom message.
• proxy_pass: Routes requests to your Ethereum node (running on localhost:8545).

4. Configure Your Ethereum Node

Ensure your node (e.g., geth) binds to localhost to prevent direct external access:

geth --http --http.addr 127.0.0.1 --http.port 8545

👉 Learn more about secure geth configurations

5. Update Your DApp’s Web3 Provider

Modify your DApp’s JavaScript to use the protected /eth endpoint:

const web3 = new Web3(new Web3.providers.HttpProvider('http://yourdomain.com/eth'));

For local development, revert to http://localhost:8545.

6. Restart Nginx

Apply changes and test the configuration:

sudo nginx -t  # Validate syntax
sudo systemctl restart nginx

Troubleshooting

• 502 Bad Gateway: Verify geth/Parity is running (systemctl status geth).
• Authentication Failures: Check /var/log/nginx/error.log for details.
• Mixed Content Errors: Ensure DApp URLs use HTTPS if Nginx is SSL-enabled.

FAQ

1. Is HTTP Basic Authentication Secure Enough?

For sensitive operations, combine it with HTTPS (SSL/TLS) to encrypt credentials in transit. Avoid using it for high-risk applications without additional layers (e.g., IP whitelisting).

2. How Do I Scale This for Multiple Users?

Add more usernames/passwords to .htpasswd. For granular access control, consider OAuth or JWT.

3. Can I Use This with MetaMask?

MetaMask doesn’t support HTTP Basic Auth. Instead, use middleware like a custom proxy or Infura for public DApps.

Advanced Tips

• HTTPS Setup: Use Let’s Encrypt to add free SSL certificates:

  sudo apt install certbot python3-certbot-nginx
  sudo certbot --nginx -d yourdomain.com

• Rate Limiting: Throttle requests to prevent abuse:

  location /eth {
      limit_req zone=eth_api burst=5 nodelay;
      # ... rest of config
  }

👉 Explore advanced Nginx security practices

Conclusion

Securing your Ethereum JSON-RPC API with Nginx and HTTP Basic Authentication is a straightforward way to mitigate risks while maintaining usability. For production environments, always pair this with HTTPS and monitor logs for suspicious activity. By following this guide, you’ve taken a critical step toward hardening your blockchain infrastructure.

Next Steps:

• Enable HTTPS for encrypted traffic.
• Set up automated log monitoring for unauthorized access attempts.
• Consider IP-based restrictions for added security.

Need help optimizing your node’s performance? Check out our expert-node tuning guide for pro tips!