# 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.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/permissions-policy/traefik/
Updated: 2026-10-24
Tested on: Traefik 2.11, 3.6 and 3.7

## In short

- 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](/guides/permissions-policy/) 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:

```sh
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](/guides/security-headers/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:

```sh
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. |

## 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`.

## Sources

- [Traefik Proxy: Headers middleware](https://doc.traefik.io/traefik/middlewares/http/headers/), Traefik Labs
- [Traefik Proxy: Routers (rules and priority)](https://doc.traefik.io/traefik/routing/routers/), Traefik Labs
- [Permissions Policy](https://w3c.github.io/webappsec-permissions-policy/), W3C
- [Permissions-Policy header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy), MDN Web Docs
