Traefik guide · Permissions-Policy

How to set Permissions-Policy on Traefik

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.

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

Present on error pages too

In short4 points
  • Add permissionsPolicy: "camera=(), microphone=(), geolocation=(), …" to a headers middleware 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 with customResponseHeaders and 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:

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

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

Shell
docker inspect --format '{{json .Config.Labels}}' <container> | tr ',' '\n' | grep traefik

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).
  • Applications that send a Feature-Policy, the header Permissions-Policy replaced (step 3).
  • A featurePolicy option in an old middleware. Traefik 2.11 turned it into a Feature-Policy header; in our test, Traefik 3.6 and 3.7 accepted it and sent nothing, without a log line. Replace it with permissionsPolicy.

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:

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

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

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

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

Shell
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

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

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