Apache guide · Permissions-Policy

How to set Permissions-Policy on Apache

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.

  • By
  • Updated
  • 5 min read
  • Tested on Apache httpd 2.4.58, 2.4.62 and 2.4.69
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Apache
permissions-policy
camera=(), microphone=(), geolocation=()

Present on error pages too

In short4 points
  • Add Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), …" to the VirtualHost, listing every feature your site does not use. With Header 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. Put Header unset Permissions-Policy before the always line.
  • To enable the camera on one path, set the header again in a <Location>. Never mix Header set and Header always set: the server's camera=() can end up last.

The short answer

Add the header to the VirtualHost of your site, listing the features you do not use:

Apache
<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>
Shell
sudo apachectl configtest && sudo apachectl graceful

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

Shell
apachectl -M | grep headers
apachectl -S
grep -rniE "Permissions-Policy|Feature-Policy|ProxyPass" /etc/apache2/ /etc/httpd/ 2>/dev/null

If 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 .htaccess or in the application behind Apache. Two headers cause trouble (step 3), and Feature-Policy can be removed.
  • Header set lines for this header. They behave differently from Header 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:

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

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

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

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

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

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

  1. Apache Module mod_headersApache HTTP Server Project

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