Origin Whitelisting with Origin Identity Secret¶
To enhance the security of your origin servers when using Nitrogen (N7), we have introduced the Origin Identity Secret (X-Nv-Access-Key
) HTTP header. This feature allows your origin to verify that incoming requests have been processed and forwarded by the N7 network, preventing unauthorized direct access.
This document explains how the X-Nv-Access-Key
works, how to manage your secret keys, and how to configure your origin server for seamless key rotation.
Overview¶
When enabled, Nitrogen will add a unique X-Nv-Access-Key
header to all requests forwarded to your origin server. The value of this header is a secret key that you can manage within the Nitrogen dashboard (dash.n7.io
).
By whitelisting requests containing a valid secret key at your origin's firewall or application layer, you ensure that only traffic routed through N7 reaches your servers. This protects your origin from direct attacks and ensures that N7's WAF and other security features are always applied.
Key Characteristics:
- Header Name:
X-Nv-Access-Key
- Key Length: 64 characters
- Key Management: Via
dash.n7.io
Active and Backup Key System for Seamless Rotation¶
To prevent downtime during key rotation, Nitrogen utilizes an Active and Backup key system:
- Active Key: This is the primary key currently being sent by N7 in the
X-Nv-Access-Key
header for requests to your origin. - Backup Key: This is a secondary key visible in your Nitrogen dashboard (
dash.n7.io
). It is not actively sent in requests but is ready to become the Active Key upon rotation.
Key Rotation Process¶
Rotating your access keys regularly is a crucial security practice. The rotation process in Nitrogen is designed to be seamless:
- Initiate Rotation: When you trigger a key rotation in the
dash.n7.io
:- The current Backup Key becomes the new Active Key. Nitrogen will immediately start sending this new Active Key in the
X-Nv-Access-Key
header. - A new Backup Key is automatically generated and displayed in the dashboard.
- The current Backup Key becomes the new Active Key. Nitrogen will immediately start sending this new Active Key in the
- Grace Period (Client-Side Configuration): During the rotation, your origin server should be configured to accept either the (now previous) Active Key or the new Active Key (which was the Backup Key). This overlap is critical to prevent request failures while you update your origin's whitelist to the new Active Key.
- Update Origin Configuration: After initiating rotation, update your origin server's whitelisting rule to recognize the new Active Key. Once confirmed, you can optionally remove the previous Active Key from your origin's allowed list, though keeping both (the current Active and current Backup) provides maximum flexibility.
This system ensures that there is no period during which valid requests from N7 would be blocked due to a key mismatch, provided your origin is configured correctly.
Configuring Your Origin Server¶
To use the X-Nv-Access-Key
for whitelisting, you need to configure your origin server (e.g., web server, WAF, load balancer) to:
- Check for the
X-Nv-Access-Key
header in incoming requests. - Validate the header's value against your known secret keys.
- Allow requests that contain a valid Active or Backup key.
- Deny or flag requests that either do not have the header or have an invalid key.
Crucial Configuration for Rotation:
To ensure zero downtime during key rotation, your origin whitelisting logic must allow requests if the X-Nv-Access-Key
matches EITHER your current Active Key OR your current Backup Key.
Specific Web Server Examples:
Nginx:
http {
# Define a map for your N7 access keys
map $http_x_nv_access_key $is_n7_traffic {
default 0;
"YOUR_NITROGEN_ACTIVE_KEY" 1;
"YOUR_NITROGEN_BACKUP_KEY" 1; # Add backup key here
}
server {
listen 80;
server_name your_origin.example.com;
location / {
if ($is_n7_traffic = 0) {
return 403; # Forbidden
}
# Your normal proxy_pass or root directives here
proxy_pass http://backend_server;
}
}
}
Note: Replace "YOUR_NITROGEN_ACTIVE_KEY"
and "YOUR_NITROGEN_BACKUP_KEY"
with the actual keys from dash.n7.io
.
AWS WAF / Application Load Balancer (ALB):
You can create a custom rule that inspects the X-Nv-Access-Key
header.
- Rule Type:
String match
orRegex match
on the header. - Header Name:
X-Nv-Access-Key
- String to match (Option 1 - Separate rules):
- Rule 1: Value is
YOUR_NITROGEN_ACTIVE_KEY
- Rule 2: Value is
YOUR_NITROGEN_BACKUP_KEY
- Combine these rules with an OR condition.
- String to match (Option 2 - Regex if supported for multiple strings):
- A regex pattern like
^(YOUR_NITROGEN_ACTIVE_KEY|YOUR_NITROGEN_BACKUP_KEY)$
- Action:
ALLOW
if the key matches, and a default action ofBLOCK
for the Web ACL if no rules match (or a specific rule to block if the header doesn't match).