- Add
header Permissions-Policy "camera=(), microphone=(), geolocation=(), …"to the site block, listing every feature your site does not use. Caddy sends it on its own 404 pages and redirects. - When the policy contains origins, wrap the value in backticks so the origins keep their double quotes. Unescaped double quotes make
caddy validatefail with a regexp error. - Behind
reverse_proxy, the application's policy comes after Caddy's, and for a feature defined in both the last one wins. Addheader_down -Permissions-Policyinside the proxy block. - To enable the camera on one path, put that path's
headerline in arouteblock. Outsideroute, the site-wide line runs last and overwrites it.
The short answer
Add the header to the site block in your Caddyfile, listing the features you do not use:
example.com {
header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
root * /var/www/example
file_server
}caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddyEvery snippet below was run on Caddy 2.9, 2.10 and 2.11 and checked with
curl, on a page, a 404, a redirect, a proxied application and an
application that was down.
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
Find every site block, header directive and proxy in your Caddyfile:
grep -nE "^[^ \t#].*\{|header|Permissions-Policy|Feature-Policy|reverse_proxy|php_fastcgi|import|route" /etc/caddy/CaddyfileYou 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 4).
- Every site that serves pages. Caddy adds no Permissions-Policy on its own.
- Proxied applications that may send a Permissions-Policy or an old Feature-Policy. Two headers cause trouble (step 3).
Step 1: write a valid value
Caddy 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 backticks, which Caddy reads as quotes that keep double quotes inside. Escaping the inner quotes with a backslash works too:
header Permissions-Policy `camera=(), fullscreen=(self "https://video.example")`
header Permissions-Policy "camera=(), fullscreen=(self \"https://video.example\")"Both lines returned the same header in our test:
HTTP/2 200
permissions-policy: camera=(), fullscreen=(self "https://video.example")Plain double quotes inside a double-quoted value do not work. Caddy ends the
value at the second quote and reads the rest of the line as a find-and-replace
with a regular expression. With a Permissions-Policy, the parentheses make
that expression invalid: caddy validate failed on every version with
error parsing regexp: missing closing ), and Caddy refused to start with
that configuration.
Step 2: which responses get the header
A plain header line acts on every response of the site. In our test:
| Response | Permissions-Policy |
|---|---|
A page from file_server |
Present |
A 404 from file_server |
Present |
A 301 from a redir in the site |
Present |
A file under /assets/ with its own header /assets/* Cache-Control … line |
Present |
| A 502 when the proxied application was down | Present |
| Caddy’s automatic HTTP to HTTPS redirect | Absent |
Unlike Nginx and Apache, there is no always flag to remember. The automatic
redirect has no page to protect. To send the same headers from several sites,
put them in a snippet that each site imports; the
security headers hub for Caddy shows one
snippet with all six security headers.
Step 3: one header behind reverse_proxy
A header line runs before the proxy, and Caddy keeps the application’s
headers after its own. Our test, with an application sending an old,
permissive policy:
HTTP/2 200
permissions-policy: camera=(), microphone=(), geolocation=()
permissions-policy: geolocation=(self), camera=*, interest-cohort=()
feature-policy: camera *Browsers read the two headers as one policy, and when a feature is defined
twice, the last definition wins. Here the application’s camera=* comes last:
any site that frames your pages may use the camera. WebSec0 reads the
combined policy the same way and grades it as a warning.
Drop the application’s headers as the response comes back from the proxy:
example.com {
header Permissions-Policy "camera=(), microphone=(), geolocation=()"
reverse_proxy 127.0.0.1:8080 {
header_down -Permissions-Policy
header_down -Feature-Policy
}
}Our test then returned a single Permissions-Policy, Caddy’s, and no
Feature-Policy, on the application’s pages and 404s, and on Caddy’s 502 when
the application was down. Do not use the > prefix instead: it replaces the
application’s value, but Caddy’s own error pages then go without the header,
as the security headers hub for Caddy
shows.
Step 4: enable a feature on one path
A video call page under /meet/ needs the camera and the microphone. A
header /meet/* … line next to the site-wide one does not work. Caddy sorts
header directives by path matcher, the most specific first and the one
without a matcher last, so the site-wide line runs after the per-path one and
overwrites it. In our test, /meet/ got camera=().
Put the per-path line in a route block. Inside route, directives run in
the order written, and the block as a whole runs after the site-wide
header:
example.com {
header Permissions-Policy "camera=(), microphone=(), geolocation=()"
route {
header /meet/* Permissions-Policy "camera=(self), microphone=(self), geolocation=()"
}
root * /var/www/example
file_server
}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=() |
Keep the site-wide line outside route: route runs after redir in
Caddy’s directive order, so a redirect would go without the header.
Verify it
Check a page, an error page and a path with its own policy. 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/meet/ | grep -i "^permissions-policy"Each should print the policy you chose for that path. Count the headers to
catch duplicates. The result should be 1:
curl -sI https://example.com/ | grep -ci '^permissions-policy:'Then open the page in Chrome with the developer console open: a syntax error shows up as “Parse of permissions policy failed”. Finally, scan the site with WebSec0. The headers report shows the value it received and whether it passes.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
error parsing regexp: missing closing ) |
Unescaped double quotes around an origin | Wrap the value in backticks. |
| No Permissions-Policy at all | Caddy adds none by default | Add the header line to every site, or import a snippet. |
Two Permissions-Policy headers, the application’s last |
The proxied application sends one too | Add header_down -Permissions-Policy inside reverse_proxy. |
Feature-Policy still sent |
The application sends it | Add header_down -Feature-Policy. |
| A feature stays disabled on its path | The per-path line is outside route, so the site-wide line overwrites it |
Put it in a route block. |
| Header missing on 502 pages | > in front of the field |
Drop the > and use header_down. |
| Chrome ignores the header | A syntax error, such as an upper-case feature name | Check the console, and fix the value as in step 1. |
| WebSec0 shows a warning | No sensitive feature disabled, or one opened with * |
Disable the features you do not use with (), and remove *. |
Server hub
Every header on Caddy
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.
Nginx
Guide ↗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.
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 Caddyfile line for Permissions-Policy?
header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()" in the site block. Add the other features your site does not use, then run caddy validate and reload.
How do I put an origin in Permissions-Policy on Caddy?
Origins must be in double quotes in the header. Wrap the whole Caddyfile value in backticks instead of double quotes, so the inner double quotes are kept. Escaping them with backslashes in a double-quoted value also works.
Why does caddy validate fail with "error parsing regexp: missing closing )"?
A double quote inside a double-quoted value ends the value early. Caddy then reads the line as a find-and-replace with a regular expression, and the parentheses of the policy make that expression invalid. Wrap the value in backticks.
My response has two Permissions-Policy headers behind reverse_proxy. What happens?
Browsers read them as one policy, and for a feature defined in both, the last definition wins. In our test the application's header came last, so its camera=* applied. Add header_down -Permissions-Policy inside reverse_proxy.
How do I allow the camera on one URL only on Caddy?
Put header /meet/* Permissions-Policy "camera=(self), microphone=(self), geolocation=()" in a route block after the site-wide line. Inside route, directives run in the order written.
References
Sources
- Permissions-Policy headerMDN Web Docs
