Understanding Magento 2’s web/secure/offloader_header: Your Fix for Redirect Chaos

On By Tiago SampaioIn Configuration, Development, Magento 2, Routing, Security

If you read our last post, “Fix Magento 2 ERR_TOO_MANY_REDIRECTS: Step-by-Step Guide“, you know that one of the sneakiest culprits behind the dreaded “Too Many Redirects” error is a Magento configuration setting called web/secure/offloader_header. It might sound like something straight out of a sci-fi movie, but it’s actually a super important piece of the Magento puzzle, especially when working behind a reverse proxy or setting up HTTPS on your local environment.

In this post, we’re going to take a deep dive into what this setting does, how it works, and how you can master it to prevent those redirect nightmares and ensure Magento is behaving exactly how you want it to. So, strap in, grab a coffee, and let’s demystify the offloader_header together.

What is web/secure/offloader_header and Why Should You Care?

At a high level, the web/secure/offloader_header setting is how Magento determines whether a request is considered secure (i.e., HTTPS) when it’s being forwarded through a proxy, load balancer, or even a local reverse proxy setup like Docker with NGINX.

The Problem: Who’s Handling SSL?

In many hosting environments or local setups, the SSL (HTTPS) connection is terminated by a reverse proxy or load balancer before it reaches the Magento application. When this happens, Magento only sees an incoming HTTP request. Without any extra context, it has no way of knowing that the original request from the browser was actually HTTPS.

That’s where offloader_header comes in. It tells Magento: “Hey, if you see this header in the request, and it’s set to a certain value, treat it like a secure (HTTPS) request.”

Without this setting properly configured, Magento might:

  • Think a secure request is actually not secure
  • Redirect endlessly between HTTP and HTTPS
  • Serve insecure URLs in templates
  • Cause login and checkout issues

This setting is crucial for Magento to understand the true nature of incoming requests in SSL-offloaded environments.

How Magento 2 Uses web/secure/offloader_header

Magento 2 uses this configuration to detect and handle secure (HTTPS) requests when they are offloaded. By default, Magento assumes that any incoming request on port 443 or using HTTPS is secure. However, in a reverse proxy scenario, Magento doesn’t see those ports or the HTTPS protocol—it just sees an HTTP request.

Magento solves this by checking for a specific HTTP header, which is expected to be injected by the proxy. The web/secure/offloader_header value is the name of that header. If Magento sees this header with an appropriate value, it treats the request as secure.

Where is it configured?

Magento Admin Panel:

  • Go to Stores > Configuration > General > Web > Secure
  • Look for the field “Offloader header”

Magento CLI:

bin/magento config:set web/secure/offloader_header X-Forwarded-Proto
bin/magento cache:flush

Database (if needed):

INSERT INTO core_config_data (scope, scope_id, path, value)
VALUES ('default', 0, 'web/secure/offloader_header', 'X-Forwarded-Proto')
ON DUPLICATE KEY UPDATE value='X-Forwarded-Proto';

Popular Values and Their Meanings

Here are a few commonly used headers that your proxy might send, and that Magento can recognize if configured properly:

1. X-Forwarded-Proto

  • Common in: NGINX, AWS ELB, Cloudflare, Docker
  • Value: https or http
  • Magento will check:
    • If X-Forwarded-Proto: https exists, treat the request as secure.

2. X-Forwarded-Ssl

  • Common in: Some older setups or proxies
  • Value: on or off
  • Magento will check:
    • If X-Forwarded-Ssl: on, treat as secure.

3. Front-End-Https

  • Common in: Certain hosting environments
  • Value: on

Each proxy or CDN might use a different header name and value. The key is to match what your infrastructure is actually sending.

Real-World Examples: Different Scenarios

Let’s walk through some common scenarios you might encounter when developing locally or deploying Magento behind a reverse proxy.

Scenario 1: Local Development with Docker + NGINX + HTTPS

  • Problem: Your browser hits https://mymagento.test, but Magento keeps redirecting you to http://mymagento.test.
  • Fix: Set offloader_header to X-Forwarded-Proto, and ensure your proxy is sending X-Forwarded-Proto: https.
bin/magento config:set web/secure/offloader_header X-Forwarded-Proto

Scenario 2: Production Site Behind Cloudflare

  • Problem: Cloudflare offloads SSL, but Magento thinks requests are insecure.
  • Fix: Cloudflare automatically sends X-Forwarded-Proto. Just configure Magento to recognize it:
bin/magento config:set web/secure/offloader_header X-Forwarded-Proto

Scenario 3: Legacy Hosting Environment

  • Problem: SSL offloading via custom reverse proxy. The proxy sends X-Forwarded-Ssl: on.
  • Fix:
bin/magento config:set web/secure/offloader_header X-Forwarded-Ssl

Try It Yourself: Explore Locally!

Want to really understand how this setting works? Try toggling it in your local Magento instance!

Step-by-step experiment:

  1. Set up your local Magento with a reverse proxy like NGINX or Docker.
  2. Access it via HTTPS (you can use a self-signed cert).
  3. Remove the offloader_header setting.
  4. Watch the redirects go wild.
  5. Now set web/secure/offloader_header to X-Forwarded-Proto.
  6. Refresh—and enjoy your working Magento again! 😎

This hands-on experience is one of the best ways to really understand what’s happening under the hood.

Conclusion

Magento 2 is a powerful e-commerce platform, but like any complex system, it needs some tuning to work properly in different environments. The web/secure/offloader_header setting is one of those under-the-radar heroes that can make or break your deployment—especially when SSL is terminated elsewhere.

In this post, we covered:

  • What offloader_header is and why it matters
  • How Magento uses this value to detect HTTPS requests
  • Common headers used by proxies and how to configure Magento to understand them
  • Real-world examples and troubleshooting scenarios

Next time you encounter the infamous “Too Many Redirects” error or wonder why Magento thinks it’s running in HTTP when it shouldn’t be—this setting should be the first thing you check.

Now go, Magento warrior! ⚔️ Configure your offloader_header, tame those redirects, and serve your store over HTTPS like a boss.

Leave a comment