upgrade-insecure-requests
Theupgrade-insecure-requests
directive instructs the browser to upgrade HTTP requests to HTTPS before fetching, helping to secure communication by avoiding mixed content. This is particularly useful when migrating large sites from HTTP to HTTPS.
Important The upgrade-insecure-requests
directive does not work in report-only mode. It must be used in enforcement mode to actually upgrade requests. In report-only mode, violations will be reported but insecure requests will not be upgraded.
Recommended Values
Recommended upgrade-insecure-requests configuration
Content-Security-Policy: upgrade-insecure-requests;
Tips & Tricks
This directive is particularly useful when migrating large sites from HTTP to HTTPS, as it reduces the need to update all resource links manually.
While this directive upgrades requests, it doesn't guarantee that the upgraded requests will succeed. The server must support HTTPS for the resources.
The upgrade happens before any requests are made, which helps prevent mixed content warnings in browsers.
How It Works
Theupgrade-insecure-requests
directive automatically upgrades HTTP requests to HTTPS before they're sent to the network. This happens transparently without modifying the actual HTML content.
Non-navigational Upgrades
Consider a website that wants to migrate from HTTP to HTTPS but has thousands of hardcoded HTTP URLs in their content management system. Instead of manually updating each link, they can add:Content-Security-Policy: upgrade-insecure-requests
<img src="http://example.com/image.png">
<img src="http://third-party.com/image.png">
<img src="https://example.com/image.png">
<img src="https://third-party.com/image.png">
Navigational Upgrades
The directive also upgrades navigational links. For example:<a href="http://example.com/">Home</a>
<a href="https://example.com/">Home</a>
<a href="http://third-party.com/">
will remain as HTTP for navigation purposes.
Use Cases
- Site Migration: When moving from HTTP to HTTPS
- Legacy Content: Handling old HTTP links without manual updates
- Third-party Content: Managing external resources that might use HTTP
- User-generated Content: Automatically securing user-submitted URLs
Additional Information
- The directive affects all insecure URLs, not just those specified in the HTML
- It's processed before other CSP directives
- The upgrade happens client-side, before any requests are made
- It doesn't modify the actual HTML - only the requests made by the browser
Relation to "Mixed Content"
Theupgrade-insecure-requests
directive operates at a fundamental level in the browser's request pipeline. It rewrites requests at the top of the Fetching algorithm, before either Mixed Content or Content Security Policy checks take effect.
Upgraded requests will not be flagged as mixed content because the upgrade happens before mixed content checks.
When `upgrade-insecure-requests` is set, the `block-all-mixed-content` directive becomes effectively a no-op, as the upgrade happens first.
Recommendation
It's recommended to use eitherupgrade-insecure-requests
OR block-all-mixed-content
, but not both:
Preferred approach: Automatically upgrade insecure requests
Content-Security-Policy: upgrade-insecure-requests;
upgrade-insecure-requests
directive is generally more flexible as it attempts to maintain compatibility while improving security, whereas block-all-mixed-content
simply blocks insecure resources without attempting to upgrade them.