upgrade-insecure-requests

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

The upgrade-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
This allows the browser to treat HTML like:
<img src="http://example.com/image.png">
<img src="http://third-party.com/image.png">
As though it had been written as:
<img src="https://example.com/image.png">
<img src="https://third-party.com/image.png">
The URLs are rewritten before any requests hit the network, making all resource requests secure with no manual updates required.

Navigational Upgrades

The directive also upgrades navigational links. For example:
<a href="http://example.com/">Home</a>
Will be treated as:
<a href="https://example.com/">Home</a>
Note that links to third-party sites will not be upgraded for navigation. For example, <a href="http://third-party.com/"> will remain as HTTP for navigation purposes.

Use Cases

  1. Site Migration: When moving from HTTP to HTTPS
  2. Legacy Content: Handling old HTTP links without manual updates
  3. Third-party Content: Managing external resources that might use HTTP
  4. 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"

The upgrade-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 either upgrade-insecure-requests OR block-all-mixed-content, but not both:

Preferred approach: Automatically upgrade insecure requests

Content-Security-Policy: upgrade-insecure-requests;
The 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.

Related Resources

External Articles

Related Documentation Sections