Get started

This page takes you from the reports your website already collects to a Permissions-Policy deployed in report-only mode, then enforced.

Before you begin

Make sure you have:

• A website that sends reports to CentralCSP. The Permissions Policy reports page shows what the builder learns from. If it shows no data, the builder still works: start from a preset and grant features by hand. Refer to Connect your site.
• Access to the server, framework, or content delivery network (CDN) configuration that sets your response headers.
• A list of the iframes your pages embed on purpose, such as a payment form, a video player, or a map.

Decide how long a period to learn from before you start. A longer period catches pages that few visitors open, such as checkout or account settings.

1. Choose the reports to learn from

To choose the period:

1. In the website sidebar, go to Builders > Permissions-Policy.
2. On the Period step, select Today, 7 days, 14 days, or 30 days. For any other range within the last 30 days, drag across the report chart instead.
3. Check the three counters: Reports, Features used, and Look like noise.
4. Select Continue.

The default period is 7 days. Today is the current calendar day in your timezone, not the last 24 hours. A website that sends a very large volume of reports is limited to 7 days at a time. On such a website the 14 days and 30 days options are hidden. If a period holds too many reports to read in time, the page asks you to pick a shorter period.

If the period holds no reports, the page says Browsers sent no Permissions-Policy reports in this period. Pick a longer period, or continue with a preset.

2. Pick a starting policy

Browsers never report the Permissions-Policy a page was served with, so the builder cannot detect yours. You start from a preset, or from the policy you paste.

To pick the starting policy:

1. On the Starting policy step, select one option:
   • Deny every listed feature: The default. Denies all 25 features of the catalog, including inside embedded frames.
   • Payment page baseline: Denies everything except payment request and passkey sign-in on your own origin.
   • Allow camera and microphone: Denies everything except camera, microphone, and fullscreen on your own origin, for video call or capture pages.
   • Your own policy: Paste the Permissions-Policy value you send today, without the header name, or write your own.
2. Check the header value under The policy you start from.
3. Select Continue.

If the builder cannot read any feature from a pasted value, the panel says so. For the exact value of each preset, refer to Starting presets.

3. Review the features

The table lists every feature of the policy you are building, with one row for your own pages (self) and one for each frame origin. Each row is already decided, with what your pages and frames used granted, and noise and third-party-only features rejected.

To review the table:

1. On the Review features step, set the flag filter to From frame.
2. Check each frame origin. Keep the ones you embed on purpose, such as your payment provider, and select Reject on any origin you do not recognize.
3. Set the flag filter to Noise. If a noise row is a feature your site really uses, select Add.
4. Set the flag filter to Third-party script. These rows start rejected. To see which scripts called the feature, select the row, then grant it only if you trust that script with the feature.
5. (Optional) Select Reject on features you are sure your pages no longer need.
6. Select Continue.

A feature marked Denied has nothing granted, so the header writes it as (). To put every decision back to the builder's recommendation, select Auto. For each column, flag, and filter, refer to Review table.

4. Deploy in report-only mode

To deploy the policy:

1. On the Deploy step, leave the mode on Report-only.
2. In the code block, copy both headers, or select Export as TXT to download both headers in a text file. The export is recorded in the audit log.
3. If the page shows Frames need their allow attribute too, you granted a feature to a frame's origin. Keep the allow attribute on that iframe, as it is today.
4. Add both headers to every HTML response your site returns.

The headers look like this example. The first declares the endpoint:

Reporting-Endpoints: centralcsp="https://MyEndpoint.report.centralcsp.com", default="https://MyEndpoint.report.centralcsp.com"

The second carries the policy. The builder writes it on one line; it is split here for reading:

Permissions-Policy-Report-Only:
    accelerometer=(),
    autoplay=(),
    browsing-topics=(),
    camera=(self),
    clipboard-read=(),
    clipboard-write=(self),
    display-capture=(),
    encrypted-media=(),
    fullscreen=(self "https://video.example.com"),
    gamepad=(),
    geolocation=(self),
    gyroscope=(),
    idle-detection=(),
    local-fonts=(),
    magnetometer=(),
    microphone=(),
    midi=(),
    payment=(self "https://pay.example.com"),
    picture-in-picture=(),
    publickey-credentials-get=(),
    screen-wake-lock=(),
    serial=(),
    storage-access=(),
    usb=(),
    xr-spatial-tracking=()

The policy has no report-to parameter. Its reports go to the default endpoint that the Reporting-Endpoints header declares.

Granting payment to https://pay.example.com in the header is only half of the delegation. The iframe must still name the feature in its allow attribute (refer to how the header relates to the iframe allow attribute):

<iframe src="https://pay.example.com/checkout" allow="payment"></iframe>

Browsers now report the features the policy would block, without blocking them.

5. Switch to enforce mode

To enforce the policy:

1. Watch the Permissions Policy reports page for at least a week. Each violation now means the policy would block a feature your pages used, and each potential violation means a frame asked for a feature the policy would deny.
2. When nothing your pages need shows up in the reports, run the builder again on that week. The builder cannot detect the policy you deployed, so select Your own policy and paste it.
3. On the Deploy step, select Enforce.
4. Replace the report-only header with the Permissions-Policy header.

Browsers now block the features the policy does not grant.

Next steps

• Permissions-Policy builder overview
• Review table
• Builder decision rules
• Permissions-Policy violation report