- Add
Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), …"to theVirtualHost, listing every feature your site does not use. WithHeader set, 404 pages and redirects go without it. - When the policy contains origins, escape their double quotes with a backslash, or wrap the whole value in single quotes.
- Behind
mod_proxy_http, the application's policy comes after Apache's, and for a feature defined in both the last one wins. PutHeader unset Permissions-Policybefore thealwaysline. - To enable the camera on one path, set the header again in a
<Location>. Never mixHeader setandHeader always set: the server'scamera=()can end up last.
The short answer
Add the header to the VirtualHost of your site, listing the features you do
not use:
<VirtualHost *:443>
ServerName example.com
DocumentRoot "/var/www/example"
SSLEngine on
SSLCertificateFile /etc/ssl/example.com/fullchain.pem
SSLCertificateKeyFile /etc/ssl/example.com/privkey.pem
Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
</VirtualHost>sudo apachectl configtest && sudo apachectl gracefulalways keeps the header on error pages and redirects. Every snippet below
was run on Apache httpd 2.4.58, 2.4.62 and 2.4.69 and checked with curl, on
a page, a 404, a redirect and a proxied application.
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
The Header directive comes from mod_headers. Check that it is loaded, then
find your virtual hosts and every existing policy:
apachectl -M | grep headers
apachectl -S
grep -rniE "Permissions-Policy|Feature-Policy|ProxyPass" /etc/apache2/ /etc/httpd/ 2>/dev/nullIf headers_module is missing, enable it with sudo a2enmod headers on
Debian and Ubuntu, or uncomment its LoadModule line in httpd.conf.
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).
- An existing Permissions-Policy or Feature-Policy, in another file, in
.htaccessor in the application behind Apache. Two headers cause trouble (step 3), andFeature-Policycan be removed. Header setlines for this header. They behave differently fromHeader always set(step 5).
Step 1: write a valid value
Apache 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").
Inside a double-quoted Apache value, escape the origin’s quotes with a backslash, or wrap the whole value in single quotes:
Header always set Permissions-Policy "camera=(), fullscreen=(self \"https://video.example\")"
Header always set Permissions-Policy 'camera=(), fullscreen=(self "https://video.example")'Both lines returned the same header in our test:
HTTP/1.1 200 OK
Permissions-Policy: camera=(), fullscreen=(self "https://video.example")To keep a long policy readable, end each line with a backslash. Apache joins the lines:
Header always set Permissions-Policy "camera=(), \
microphone=(), \
geolocation=()"Our test returned camera=(), microphone=(), geolocation=(), with the
indentation kept as spaces after each comma. The header’s syntax, defined in
RFC 9651, allows spaces after
a comma, and WebSec0 parses this value like the one-line version. Break lines
only after a comma.
Step 2: keep it on error pages and redirects
Apache keeps two tables of response headers. Header set writes to the one
used for successful responses; Header always set writes to the one that is
also sent on errors and redirects. Our test with
Header set Permissions-Policy "camera=(), microphone=(), geolocation=()":
HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=()
HTTP/1.1 404 Not Found
(no Permissions-Policy header)
HTTP/1.1 301 Moved Permanently
(no Permissions-Policy header)With Header always set, all three responses carried the header. An error
page that loads analytics or a chat widget would otherwise run with every
feature at its default.
A Header line in the VirtualHost also reaches every <Location> and
<Directory>, even one that sets another header. Our test returned the
policy and Cache-Control for a file under a <Location "/assets/"> that
only set Cache-Control. To cover every site at once, put the line in the
server configuration; the
security headers hub for Apache shows one
file with all six security headers, loaded that way.
Step 3: one header behind a reverse proxy
With mod_proxy_http, the application’s headers land in the default table and
Header always set adds yours in the other one. Our test, with an
application sending an old, permissive policy:
HTTP/1.1 200 OK
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.
Pick one owner. If it is Apache, remove the application’s headers from the
default table, then set yours in the always table:
<VirtualHost *:443>
# ...
ProxyPass "/" "http://127.0.0.1:8080/"
Header unset Permissions-Policy
Header unset Feature-Policy
Header always set Permissions-Policy "camera=(), microphone=(), geolocation=()"
</VirtualHost>Our test then returned a single Permissions-Policy, Apache’s, and no
Feature-Policy, on the application’s pages and on its 404s. Apache’s
documentation notes that CGI scripts and mod_proxy_fcgi, which runs
PHP-FPM, put their headers in the always table, where Header always set
replaces them.
Step 4: enable a feature on one path
A video call page under /meet/ needs the camera and the microphone. Set the
header again in a <Location> and keep everything else disabled:
<VirtualHost *:443>
# ...
Header always set Permissions-Policy "camera=(), microphone=(), geolocation=()"
<Location "/meet/">
Header always set Permissions-Policy "camera=(self), microphone=(self), geolocation=()"
</Location>
</VirtualHost>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=() |
Apache merges <Location> sections after the virtual host, so the later
set replaces the value. Unlike Nginx, the other headers of the virtual host
stay in place, with nothing to repeat.
Step 5: never mix Header set and Header always set
The two tables combine, and in our tests Apache sent the always table first.
With Header set in the virtual host and the <Location "/meet/"> from step
4, our test returned for /meet/:
HTTP/1.1 200 OK
Permissions-Policy: camera=(self), microphone=(self), geolocation=()
Permissions-Policy: camera=(), microphone=(), geolocation=()The server’s camera=() comes last and wins, so the video call page cannot
use the camera. Use Header always set on every line for this 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 |
|---|---|---|
Invalid command 'Header' |
mod_headers is not loaded |
a2enmod headers, or uncomment its LoadModule line. |
| Header missing on 404 pages or redirects | Header set without always |
Write Header always set. |
Two Permissions-Policy headers, the application’s last |
The proxied application sends one too | Add Header unset Permissions-Policy before the always line. |
Feature-Policy still sent |
The application sends it | Add Header unset Feature-Policy. |
| A feature stays disabled on its path | Header set in the virtual host comes last |
Use Header always set everywhere. |
| Chrome ignores the header | A syntax error, such as an origin without double quotes | Check the console, and quote origins 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 *. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | apachectl configtest && apachectl graceful, then purge the CDN. |
Server hub
Every header on Apache
Other web servers
Permissions-Policy on other servers
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.
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 Apache line for Permissions-Policy?
Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()" in the VirtualHost. Add the other features your site does not use, then run apachectl configtest and apachectl graceful.
How do I put an origin in Permissions-Policy on Apache?
Origins must be in double quotes in the header. Escape them inside a double-quoted Apache value, as in "fullscreen=(self \"https://video.example\")", or wrap the whole value in single quotes. Both returned the same header in our test.
Why is Permissions-Policy missing on my 404 pages or redirects?
Header set without always writes to the table Apache uses for successful responses only. Error pages and redirects that Apache generates use the always table. Write Header always set.
My response has two Permissions-Policy headers. What happens?
Browsers read them as one policy, and when a feature is defined in both, the last definition wins. Behind mod_proxy_http, the application's header came last in our test, so its camera=* applied. Add Header unset Permissions-Policy before Header always set.
How do I allow the camera on one URL only on Apache?
Add Header always set Permissions-Policy "camera=(self), microphone=(self), geolocation=()" in a <Location> for that path. It replaces the virtual host's value there, error pages included, and the other headers stay in place.
Can I split a long Permissions-Policy over several lines in Apache?
Yes. End each line with a backslash. Apache joins the lines and keeps the indentation as spaces after each comma, which the header's syntax allows. Do not put the backslash inside a feature's parentheses.
References
Sources
- Apache Module mod_headersApache HTTP Server Project
- Configuration Files: syntax and line continuationApache HTTP Server Project
- Permissions-Policy headerMDN Web Docs
