Caddy guide · Permissions-Policy

How to set Permissions-Policy on Caddy

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.

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

Present on error pages too

In short4 points
  • 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 validate fail 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. Add header_down -Permissions-Policy inside the proxy block.
  • To enable the camera on one path, put that path's header line in a route block. Outside route, 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:

Caddyfile
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
}
Shell
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

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

Shell
grep -nE "^[^ \t#].*\{|header|Permissions-Policy|Feature-Policy|reverse_proxy|php_fastcgi|import|route" /etc/caddy/Caddyfile

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

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

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

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

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

Shell
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

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

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