Nginx guide · Permissions-Policy

How to set Permissions-Policy on Nginx

Set Permissions-Policy on Nginx with add_header and always, quote origins correctly, keep it on every location and enable a feature on one path only. Tested configs.

  • By
  • Updated
  • 5 min read
  • Tested on nginx 1.28, 1.30 and 1.31
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
nginx
permissions-policy
camera=(), microphone=(), geolocation=()

Present on error pages too

In short5 points
  • Add add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), …" always; to the server block, 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. A location with its own add_header drops it too: use an include file or add_header_inherit merge; (nginx 1.29.3+).
  • To enable the camera on one path, give that location its own header. Under add_header_inherit merge;, add add_header_inherit off; there, or the server's camera=() 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:

Nginx
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;
}
Shell
sudo nginx -t && sudo systemctl reload nginx

always 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:

Shell
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-Policy can 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:

Nginx
add_header Permissions-Policy 'camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")' always;

Our test returned the value unchanged:

HTTP
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
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:

Nginx
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:

Nginx
# /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;
Nginx
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:

Nginx
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
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:

Nginx
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:

Nginx
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
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:

Nginx
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:

Shell
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:

Shell
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

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

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and security headers, including Permissions-Policy, in a few seconds. Free, no account.

Scan your site