4 min read
Overview
Security is one of the most significant aspects when developing an application. If a resource like an endpoint falls into the hands of an unauthorized individual, it can exhaust your limits and resources. In this guide, we will see how to avoid this and learn how to set up a referrer whitelist on a QuickNode endpoint.
The Referrer Whitelist security feature is only available to users on the Build plan or above.
What is Referrer Whitelisting?
First, let's clarify what a referrer is. In the HTTP standard, 'referrer' is commonly spelled 'referer.' It is part of the HTTP request header that indicates the origin of a web request, usually pointing to the web page that linked to a requested resource. This information helps servers identify the source of requests.
In the context of QuickNode, referrer whitelisting is a crucial security feature that allows developers building decentralized applications (dApps) to specify which domains are permitted to make requests to their endpoints. Imagine you are developing a dApp that interacts with the blockchain using your QuickNode endpoint. When your codebase is hosted on a platform like GitHub, your active QuickNode endpoint URL might become publicly accessible. If someone obtains this URL, they could make unauthorized calls to your endpoint, resulting in excess usage not initiated by you.
This is where QuickNode's Referrer Whitelist feature becomes valuable. By whitelisting a referrer, you can restrict requests to only those originating from specific domains, rejecting all others. This ensures that only legitimate requests from approved sources are processed by your endpoint.
Implementing referrer whitelisting enhances the security of your applications and helps prevent unauthorized access to your QuickNode endpoints.
How to Set Up a Referrer in QuickNode
Let us have a look at how we can set up a referrer whitelist with QuickNode. First of all, you will need access to an endpoint. If you don't have it already, you can easily sign up with a free QuickNode account here, set up an endpoint.
After setting up your endpoint, visit the Security section for that endpoint and go to the Referrer section.
Enable referrer whitelist by clicking the referrer toggle. Then, enter the desired hostname or domain you want to whitelist, excluding URL fragments such as #section or /resource, and any user information like username:password. Simply input the domain without including the HTTP/HTTPS protocol. You can check the examples below for guidance:
| Correct (✅) | Incorrect (❌) |
|---|---|
| etherflow.quiknode.io | https://etherflow.quiknode.io/ |
| mysite.example.com | https://mysite.example.com/#about |
| app.example.net | app.example.net/resource |
| docs.yourdomain.org | docs.yourdomain.org/resource/page |
Now, only the requests to your endpoint made directly from https://etherflow.quiknode.io/ will be served. Let's test this!
Calls From a Whitelisted Domain
EtherFlow is a tool that makes it easier to send RPC calls to endpoints. Thus, we will use EtherFlow domain as a whitelisted referrer. If you want to use it as well, feel free to follow the steps below:
- Visit EtherFlow.
- Enter your endpoint's HTTP Provider URL in the box at the top.
- Choose a Web3 library (either Web3.js or Ethers.js).
- Select a method from the available options.
- Click the Send Request To Node button.
As you can see, the endpoint is responding completely fine on that domain now. Let us try to make a cURL call to our endpoint.
cURL Call Without a Referer Header
Open your terminal and run the following command. Do not forget to replace the <YOUR_QUICKNODE_ENDPOINT_URL> placeholder in the CURL request below with the your QuickNode endpoint URL.
curl --location '<YOUR_QUICKNODE_ENDPOINT_URL>' \
--header 'Content-Type: application/json' \
--data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'
As you can see, the endpoint did not respond and gave an UNAUTHORIZED error. It will only respond to the requests made by the whitelisted referrer.
cURL Call With a Referer Header
While using this feature, you must make sure that all the requests your website is sending to the endpoint have the Referer HTTP Header set exactly to what you've whitelisted in the QuickNode UI. For example, if you've added example.com in the QuickNode UI, your HTTP request should have https://example.com as the Referer Header, and if you're using the WSS endpoint the Origin header must be set to exactly what you've whitelisted in the UI.
Let's try to make a cURL call with the referer header to our endpoint.
Open your terminal and run the following command. Do not forget to replace the <YOUR_QUICKNODE_ENDPOINT_URL> placeholder in the CURL request below with your QuickNode endpoint URL. Also, modify the Referer Header with your whitelisted domain.
Logs for Simplified Debugging
You can now access Logs for your RPC endpoints, helping you troubleshoot issues more effectively. If you encounter an issue with your RPC calls, simply check the logs in your QuickNode dashboard to identify and resolve problems quickly. Learn more about log history limits on our pricing page.
curl --location '<YOUR_QUICKNODE_ENDPOINT_URL>' \
--header 'Content-Type: application/json' \
--header 'Referer: https://etherflow.quiknode.io' \
--data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'
As you can see, the endpoint responded without any error.
This security feature is very important to block unauthorized access to your endpoint. However, it's worth noting that whitelist referrers are not foolproof. If someone has your endpoint URL and knows the whitelisted referrer, they can potentially access your endpoint.
Another notable security feature is the ability to manage authentication tokens. If you suspect that someone has access to your endpoint URL, you can generate a new token and delete the existing one. This action will render the old endpoint URL obsolete.
Additional Resources
For further information on enhancing your endpoint security, consider exploring the following guides. These resources provide valuable insights and best practices for securing your QuickNode endpoints.
- How to Protect Your Endpoint - Front End Best Practices
- How to Implement JSON Web Tokens (JWT) Authorization with QuickNode
- How to Secure Your Endpoint Using Endpoint Armor
- How to Set Up Multi-Token Authentication on QuickNode
- How to Set Up Domain Masking on QuickNode
Conclusion
In this guide, we learned how to set the Referrer Header correctly in HTTP requests to utilize QuickNode's referrer whitelisting feature, ensuring secure and authorized access to your endpoints.
Subscribe to our newsletter for more articles and guides on Ethereum. If you have any feedback, feel free to reach out to us via Twitter. You can always chat with us on our Discord community server, featuring some of the coolest developers you'll ever meet :)
We ❤️ Feedback!
Let us know if you have any feedback or requests for new topics. We'd love to hear from you.