[Informative] Controlling Access to XDC Node RPC Endpoints

Notes:

• These instructions relate to XDC Mainnet Nodes.
• Appendix A shows process modifications needed for Apothem Testnet nodes.
• Metamask cannot presently access an RPC protected with htpasswd/nginx method for username/pw authentication. There is an alternate Metamask-friendly solution which I will cover in another subsequent article if there is demand.

Implementing middleware access controls for the RPC interface of an XDC node provides benefits in terms of security and control over who can access and interact with the node. By restricting access to trusted entities, you reduce the risk of unauthorized access, data breaches, and malicious attacks. This is important as XDC nodes often contain sensitive information and control over valuable assets.

One method of achieving this is by using Nginx as a reverse proxy and then leveraging Nginx's built-in features including access control lists (ACLs) and authentication mechanisms. This is the method we will cover below.

Getting Started

For the purposes of this article, we will assume that you are already using Nginx to provide SSL/TLS encryption to your RPC as described in this article.

The steps to now add access control functionality are:

• Install and set up software to establish usernames and hashed passwords. We will use htpasswd for this
• Modify nginx.conf to activate basic user authentication and access control lists, then restart Nginx
• Test our newly secured RPC access

Setting Usernames and Passwords

First we need to install the apache2-utils package (if not already installed) to use the htpasswd tool:

sudo apt-get update
sudo apt-get install apache2-utils

Next we create the .htpasswd file with the desired username and password:

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

Replace username with your preferred username. You will be prompted to enter and confirm the password.

Note that the -c option when using htpasswd creates a new file with that name. It is only used the first time when creating the .htpasswd file. If you use it again, it will overwrite any existing file with the same name (and you will therefore lose the contents of any existing file, including any existing username/passwords already stored in it).

To add subsequent usernames and passwords, use the same command, but without the -c option:

sudo htpasswd /etc/nginx/.htpasswd username

Once created, it is important to set appropriate file permissions for the .htpasswd file to protect it, as it contains sensitive information (username and password hashes) used for authentication.

First we will ensure that the .htpasswd file is owned by root and belongs to the group www-data that the web server runs as:

sudo chown root:www-data /etc/nginx/.htpasswd

Now we restrict access to the .htpasswd file so that the web server process can still read it but others cannot:

sudo chmod 0640 /etc/nginx/.htpasswd

Now that our usernames and passwords have been set up and secured, we move on to modifying our Nginx setup.

Modifying Nginx

Background

When previously establishing SSL/TLS encryption by using Nginx, we added the following code to the http block in nginx.conf:

        ##
        # XDC Node RPC Reverse Proxy
        ##

        server {
            listen 443 ssl;
            server_name <your_ip_address>;

            ssl_certificate /etc/ssl/certs/cert.pem;
            ssl_certificate_key /etc/ssl/private/key.pem;

            location /rpc {
                proxy_pass http://<docker_container_ip>:8545;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
            }
        }

Adding RPC Authentication / ACL

In order to add RPC authentication functionality to our Nginx implementation, we first need to open the Nginx configuration file in nano for editing:

sudo nano /etc/nginx/nginx.conf

Next we just need to modify the code block shown above by adding a few more lines which can be seen in this modified code block:

        ##
        # XDC Node RPC Reverse Proxy
        ##

        server {
            listen 443 ssl;
            server_name <your_ip_address>;

            ssl_certificate /etc/ssl/certs/cert.pem;
            ssl_certificate_key /etc/ssl/private/key.pem;

            location /rpc {
                # Enable basic authentication
                auth_basic "Restricted Access";
                auth_basic_user_file /etc/nginx/.htpasswd;

                # Whitelist or blacklist IP addresses using ACLs
                # Whitelist example: allow only specific IP addresses
                allow 192.168.0.1;
                allow 10.0.0.0/24;
                deny all;

                proxy_pass http://<docker_container_ip>:8545;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
            }
        }

By adding the auth_basic and auth_basic_user_file directives, we enable basic authentication and specify the file containing the username and password information (which we created earlier above with htpasswd).

The allow and deny directives define access control lists. In this example, the configuration allows only specific IP addresses (whitelisting) to access the /rpc location. You can modify the IP addresses or use different ACLs to suit your requirements. If using the code block above, please remember to remove or comment-out the example items we have provided in the ACL. You can find more information on the rules of setting up ACLs here.

Once completed, save the changes and exit nano:

Press "CTRL+X"
Press "y"
Press "ENTER"

Now we check that our nginx.conf file is ok:

sudo nginx -t

If the configuration test is successful, reload Nginx to apply the changes:

sudo systemctl reload nginx

With this configuration, clients accessing the /rpc location will be prompted for a username and password. Additionally, only the specified IP addresses will be allowed to access the RPC, effectively implementing our desired access controls.

Testing RPC Authentication

You can now test the authentication challenge on your XDC RPC by using a web browser and going to https://<your_nodes_ip_address>/rpc.

You should be prompted to enter your username and password to access the RPC.

Congratulations you have just added authentication to your XDC Mainnet RPC endpoint (with user-level granularity)!

Appendix A - Modifications for Apothem Testnet Nodes

The only real modification required is to ensure, if using the code block above, that we use the correct docker container PORT number for your apothem testnet node. The docker port number 8545 shown above is for mainnet XDC nodes. Apothem testnet nodes use docker port 8555.

In case of any technical queries on XDC Network, feel free to drop your queries on XDC.Dev forum.

Quick links:

XinFin.org
XDC Chain Network Tools and Documents
XDC Network Explorer
XDC Dev Forum
Beta — XDC Web Wallet
XDC faucet
XDC faucet - Blocksscan

XinFin — XDC Social Links:

Twitter
GitHub
Telegram
Facebook
LinkedIn
YouTube