- Add
permissionsPolicy: "camera=(), microphone=(), geolocation=(), …"to aheadersmiddleware and list it on the router of your site, listing every feature your site does not use. - When the policy contains origins, wrap the YAML value in single quotes so the origins keep their double quotes.
- Traefik replaces the application's Permissions-Policy but passes on its old
Feature-Policy. Remove it withcustomResponseHeadersand an empty value. - To enable the camera on one path, add a router for it with a second middleware, listed before the default one. Listed after, the default
camera=()wins.
The short answer
Define a headers middleware with the policy and attach it to the router of
your site. In a dynamic configuration file:
http:
middlewares:
permissions-policy:
headers:
permissionsPolicy: "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
routers:
site:
rule: "Host(`example.com`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [permissions-policy]With Docker labels:
services:
app:
image: nginx:1.30
labels:
- "traefik.enable=true"
- "traefik.http.routers.app.rule=Host(`example.com`)"
- "traefik.http.routers.app.entrypoints=websecure"
- "traefik.http.routers.app.tls=true"
- "traefik.http.routers.app.middlewares=permissions-policy"
- "traefik.http.middlewares.permissions-policy.headers.permissionsPolicy=camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"Every snippet below was run on Traefik 2.11, 3.6 and 3.7, in front of Nginx
containers, and checked with curl on a page, a 404, an application that
sends its own policy 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
A middleware does nothing until a router lists it. Check which routers exist and which middlewares they use, in the Traefik dashboard or in your labels:
docker inspect --format '{{json .Config.Labels}}' <container> | tr ',' '\n' | grep traefikYou 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).
- Applications that send a Feature-Policy, the header Permissions-Policy replaced (step 3).
- A
featurePolicyoption in an old middleware. Traefik 2.11 turned it into aFeature-Policyheader; in our test, Traefik 3.6 and 3.7 accepted it and sent nothing, without a log line. Replace it withpermissionsPolicy.
Step 1: write a valid value
Traefik 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 YAML so the double quotes reach the browser:
http:
middlewares:
permissions-policy:
headers:
permissionsPolicy: 'camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")'In Docker Compose, wrap the whole label in single quotes for the same reason:
- 'traefik.http.middlewares.permissions-policy.headers.permissionsPolicy=camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")'Inside double quotes, the origin’s quotes end the YAML string early. In our
test, Traefik logged yaml: line 4: did not find expected key, rejected the
whole file, and every router in it answered 404. With single quotes, our test
returned the value unchanged, with the file provider and with labels:
HTTP/2 200
permissions-policy: camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")Step 2: which responses get the header
The middleware acts on everything that goes through the router. In our test:
| Response | Permissions-Policy |
|---|---|
| A page from the application | Present |
| A 404 from the application | Present |
A page where the application sends camera=* |
Present once, with the middleware’s value |
| A 502 from Traefik when the application did not answer | Present |
| The entry point’s HTTP to HTTPS redirect | Absent |
Unlike Nginx, Apache and Caddy, there is no always flag to remember. To send
the same headers on every router, attach the middleware to the HTTPS entry
point. The security headers hub for Traefik
shows that option and its cost: per-path values on routers stop working.
Step 3: drop the application’s Feature-Policy
Traefik replaces the application’s Permissions-Policy, but it does not touch
other headers. Our test, with an application sending
Feature-Policy: camera * next to its own policy:
HTTP/2 200
permissions-policy: camera=(), microphone=(), geolocation=()
feature-policy: camera *Feature-Policy is the older name of this header. Keeping it sends a second policy that contradicts yours. Remove it in the same middleware:
http:
middlewares:
permissions-policy:
headers:
permissionsPolicy: "camera=(), microphone=(), geolocation=()"
customResponseHeaders:
Feature-Policy: ""Our test then returned no Feature-Policy, on pages and 404s. An empty value in
customResponseHeaders removes the header.
Step 4: enable a feature on one path
A video call page under /meet/ needs the camera and the microphone. Add a
router for that path with a second middleware:
http:
middlewares:
permissions-meet:
headers:
permissionsPolicy: "camera=(self), microphone=(self), geolocation=()"
routers:
site-meet:
rule: "Host(`example.com`) && PathPrefix(`/meet/`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [permissions-meet, permissions-policy]Traefik gives priority to the longer rule, so this router wins for /meet/
URLs. 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=() |
The order in middlewares matters: the first middleware in the list modifies
the response last, so its value wins. With
[permissions-policy, permissions-meet], our test returned camera=() on
/meet/, and the video call page cannot use the camera. Keeping the default
middleware in the list keeps your other security headers on the path.
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 -iE "^(permissions|feature)-policy"
curl -sI https://example.com/does-not-exist | grep -iE "^(permissions|feature)-policy"
curl -sI https://example.com/meet/ | grep -iE "^(permissions|feature)-policy"Each should print the policy you chose for that path, and no Feature-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 |
|---|---|---|
| No Permissions-Policy at all | No router lists the middleware | Add it to each HTTPS router’s middlewares, or to the entry point. |
Every router in the file answers 404, did not find expected key in the logs |
An origin’s double quotes inside a double-quoted YAML value | Wrap the value, or the Compose label, in single quotes. |
| No policy at all on Traefik 3 | The middleware uses the old featurePolicy option |
Replace it with permissionsPolicy. |
Feature-Policy still sent |
The application sends it | Add Feature-Policy: "" under customResponseHeaders. |
| A feature stays disabled on its path | The override is listed after the default middleware, or the default is on the entry point | List the override first, and attach the default to routers. |
| 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 *. |
| No header on a 404 for an unknown host | Traefik answers before any router | Expected: the response has no body to protect. |
Server hub
Every header on Traefik
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.
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.
Questions
Frequently asked questions
How do I set Permissions-Policy in Traefik?
Add permissionsPolicy to a headers middleware, or the label traefik.http.middlewares.<name>.headers.permissionsPolicy=camera=(), microphone=(), geolocation=(), and list the middleware on the router.
How do I put an origin in Permissions-Policy on Traefik?
In a YAML file, wrap the value in single quotes: permissionsPolicy: 'fullscreen=(self "https://video.example")'. In Docker Compose, wrap the whole label in single quotes for the same reason.
Does Traefik keep the application's Permissions-Policy?
No. When the middleware sets the header, Traefik replaces the application's value. An old Feature-Policy header from the application is passed on, though: remove it with customResponseHeaders and Feature-Policy: "".
How do I allow the camera on one URL only on Traefik?
Add a router with a PathPrefix rule for that path and a middleware with permissionsPolicy: "camera=(self), microphone=(self), geolocation=()". List it before the default middleware: the first one in the list writes the response headers last.
Does the featurePolicy option still work in Traefik?
Not on Traefik 3. In our test, Traefik 2.11 sent a Feature-Policy header from it, while 3.6 and 3.7 accepted the option and sent nothing, without a log line. Use permissionsPolicy.
References
Sources
- Traefik Proxy: Headers middlewareTraefik Labs
- Traefik Proxy: Routers (rules and priority)Traefik Labs
- Permissions-Policy headerMDN Web Docs
