- Add
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), …" always;to theserverblock, listing every feature your site does not use. - When the policy contains origins, wrap the Nginx value in single quotes so the origins keep their double quotes:
'fullscreen=(self "https://video.example")'. - Without
always, 404 and 500 pages are sent without the header. Alocationwith its ownadd_headerdrops it too: use anincludefile oradd_header_inherit merge;(nginx 1.29.3+). - To enable the camera on one path, give that
locationits own header. Underadd_header_inherit merge;, addadd_header_inherit off;there, or the server'scamera=()comes last and wins. - Check the browser console after deploying: Chrome ignores the whole header on a syntax error.
The short answer
Add the header to the server block of your site, listing the features you
do not use:
server {
listen 443 ssl;
http2 on;
server_name example.com;
ssl_certificate /etc/ssl/example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/example.com/privkey.pem;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()" always;
}sudo nginx -t && sudo systemctl reload nginxalways keeps the header on error pages. Every snippet below was run on
nginx 1.28, 1.30 and 1.31 and checked with curl, on a page, a 404 and a
nested location. We also loaded the policy above in Chrome 152 and checked
that all 14 features were disabled.
Remove from the list any feature your site uses. The Permissions-Policy overview explains each feature, the syntax and why only Chromium browsers apply the header.
Before you start
List every add_header, every include and every proxied application in the
merged configuration:
sudo nginx -T | grep -niE "server_name|add_header|include|proxy_pass|fastcgi_pass|permissions-policy|feature-policy"You are looking for:
- Features your pages use, such as a video call page that needs the camera, or a checkout that uses the Payment Request API (step 5).
- Locations with their own
add_header. They drop the server-level header (step 3). - An existing Permissions-Policy or Feature-Policy in Nginx or in the
application. Two headers cause trouble (step 4), and
Feature-Policycan be removed.
Step 1: write a valid value
Nginx does not check the value. Chrome does, and ignores the whole header on a syntax error:
- Lower-case feature names, no spaces around
=, commas between features, no trailing comma. ()to disable,(self)for your origin,*for any origin.- Origins in double quotes:
(self "https://video.example").
When the value contains origins, wrap it in single quotes in Nginx so the double quotes reach the browser:
add_header Permissions-Policy 'camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")' always;Our test returned the value unchanged:
HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")Keep the policy on one line, even if it is long. Nginx accepts a quoted value that spans several lines, but in our test it sent the line break inside the header value, which makes the header invalid.
Step 2: keep it on error pages
Without always, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303,
304, 307 and 308 responses. Our test with
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()";:
HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=()
HTTP/1.1 404 Not Found
(no Permissions-Policy header)An error page that loads analytics or a chat widget then runs with every
feature at its default. Keep always on the line.
Step 3: keep it on every location
add_header directives are inherited from the parent block only if the
current block has none. Here, files under /assets/ are served without
Permissions-Policy:
server {
listen 443 ssl;
server_name example.com;
# ssl_certificate lines...
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
location /assets/ {
# This one line removes the server-level Permissions-Policy for /assets/.
add_header Cache-Control "public, max-age=31536000, immutable" always;
}
}The fix that works on every version is a snippet you include wherever a block sets its own headers:
# /etc/nginx/snippets/security-headers.conf
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()" always;server {
listen 443 ssl;
server_name example.com;
# ssl_certificate lines...
include /etc/nginx/snippets/security-headers.conf;
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable" always;
include /etc/nginx/snippets/security-headers.conf;
}
}On nginx 1.29.3 or later, which includes the 1.30 stable branch,
add_header_inherit merge; makes nested blocks add their headers to the
parent’s instead of replacing them:
server {
listen 443 ssl;
server_name example.com;
# ssl_certificate lines...
add_header_inherit merge;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
location /assets/ {
# Sent together with the server-level Permissions-Policy.
add_header Cache-Control "public, max-age=31536000, immutable" always;
}
}nginx 1.28 rejects it with unknown directive "add_header_inherit". The
Referrer-Policy guide for Nginx and the
X-Frame-Options guide for Nginx use the same
snippet for their headers.
Step 4: one header behind a reverse proxy
When Nginx proxies an application that sends its own Permissions-Policy and adds its own line, the response carries both, the upstream’s first. Our test, with an application sending an old policy:
HTTP/1.1 200 OK
Permissions-Policy: geolocation=(self), interest-cohort=()
Permissions-Policy: camera=(), microphone=(), geolocation=()Browsers merge the two, and when a feature appears in both, the last
definition wins. In Chrome 152, geolocation ended up disabled by Nginx’s
header, and the upstream’s obsolete interest-cohort stayed in the policy.
When the two headers disagree, the result depends on their order, which is
easy to get wrong.
Pick one owner. If it is Nginx, hide the upstream’s header:
location / {
proxy_pass http://app;
proxy_hide_header Permissions-Policy;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
}Use fastcgi_hide_header for PHP-FPM and uwsgi_hide_header for uWSGI. Hide
Feature-Policy the same way if the application still sends it.
Step 5: enable a feature on one path
A video call page under /meet/ needs the camera and the microphone. Give
that location its own header and keep everything else disabled:
server {
listen 443 ssl;
server_name example.com;
# ssl_certificate lines...
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
location /meet/ {
add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;
# Repeat your other security headers here.
}
}What our test returned:
| URL | Permissions-Policy |
|---|---|
/ |
camera=(), microphone=(), geolocation=() |
/meet/ |
camera=(self), microphone=(self), geolocation=() |
/meet/does-not-exist (404) |
camera=(self), microphone=(self), geolocation=() |
Because the location sets its own add_header, it inherits nothing from the
server block, so repeat your other security headers in it.
With add_header_inherit merge; at server level, Nginx sends the location’s
header first and the server’s after it:
HTTP/1.1 200 OK
Permissions-Policy: camera=(self), microphone=(self), geolocation=()
Permissions-Policy: camera=(), microphone=(), geolocation=()The server’s camera=() comes last and wins: in Chrome 152, the camera and
microphone stayed disabled on /meet/. Add add_header_inherit off; as the
first line of that location:
location /meet/ {
add_header_inherit off;
add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;
}Our test then returned only the location’s header.
Verify it
Check a page, an error page and one URL in every location that sets its own
headers. Use your own host name:
curl -sI https://example.com/ | grep -i "^permissions-policy"
curl -sI https://example.com/does-not-exist | grep -i "^permissions-policy"
curl -sI https://example.com/assets/app.css | grep -i "^permissions-policy"Each should print your policy. Count the headers to catch duplicates. The
result should be 1:
curl -sI https://example.com/ | grep -ci '^permissions-policy:'curl cannot tell whether the browser accepts the value. Open the page in
Chrome, open the developer tools console and look for “Error with
Permissions-Policy header”. Then scan the site with WebSec0: it parses the
header like Chrome and fails it on a syntax error.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Header missing on 404 or 500 pages | add_header without always |
Add always to the line. |
| Header missing on some URLs | That location has its own add_header |
Include the snippet there, or use add_header_inherit merge; (1.29.3+). |
| Console: “Parse of permissions policy failed”, WebSec0 fails the header | Syntax error in the value | Lower-case names, no spaces around =, no trailing comma, origins in double quotes. |
| WebSec0 shows a warning | No sensitive feature set to (), or one set to * |
Disable the features you do not use, such as camera=(), and remove *. |
| Console: “Invalid allowlist item” | An origin without double quotes, or none |
Quote origins; use () to disable. |
nginx -t fails with unexpected "h" |
Unescaped double quotes inside a double-quoted value | Wrap the value in single quotes. |
| Header value contains a line break | The value spans several lines in the configuration | Put the whole value on one line. |
Two Permissions-Policy headers |
The upstream application sends one too | proxy_hide_header Permissions-Policy; or remove the Nginx line. |
| A feature stays disabled on one path | add_header_inherit merge; puts the server’s header last |
Add add_header_inherit off; in that location. |
unknown directive "add_header_inherit" |
nginx older than 1.29.3 | Upgrade, or use the include approach. |
Server hub
Every header on Nginx
Other web servers
Permissions-Policy on other servers
Apache
Guide ↗Set Permissions-Policy on Apache with Header always set, quote origins correctly, enable a feature on one path and stop a proxied app's policy winning. Tested configs.
Caddy
Guide ↗Set Permissions-Policy on Caddy with the header directive, quote origins with backticks, enable a feature on one path and stop a proxied app's policy winning. Tested.
Traefik
Guide ↗Set Permissions-Policy on Traefik with the permissionsPolicy option, quote origins in YAML and labels, drop an old Feature-Policy, enable a feature per path. Tested.
Questions
Frequently asked questions
What is the Nginx line for Permissions-Policy?
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()" always; in the server block. Add the other features your site does not use, then run nginx -t and reload.
How do I put an origin in Permissions-Policy on Nginx?
Origins must be in double quotes in the header, so wrap the whole Nginx value in single quotes: add_header Permissions-Policy 'camera=(self "https://meet.example")' always;. Escaping the inner quotes with backslashes in a double-quoted string also works.
Why is Permissions-Policy missing on my 404 pages?
Without the always parameter, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses. Add always at the end of the add_header line.
My response has two Permissions-Policy headers. What happens?
Browsers combine them, and when a feature is defined in both, the last definition wins. Behind a proxy, Nginx's header comes after the application's. Keep one with proxy_hide_header Permissions-Policy;.
How do I allow the camera on one URL only?
Give that location its own add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;. It no longer inherits the server-level headers, so repeat the others there. With add_header_inherit merge;, add add_header_inherit off; in that location.
Nginx accepts my header but Chrome ignores it. Why?
Nginx does not check the value. A syntax error, such as an upper-case feature name, spaces around = or a trailing comma, makes Chrome drop the whole header and log "Parse of permissions policy failed" in the console.
References
Sources
- Permissions-Policy headerMDN Web Docs
