Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme environ

[Klaas van Schelven]

Looking at the documentation of ​SECURE_PROXY_SSL_HEADER it seems this is an absolutely required setting to get is_secure working correctly when behind a proxy.

However, this is not the case: Django's own WSGI handler inspects the environment value ​wsgi.url_scheme.

This value is "occasionally" set, e.g. when running in the ​default Gunicorn setup (and it happens to be set based on the exact same header as in the case of Django).

This is surprising (in the bad way)...

Perhaps the best way forward is simply to note that, depending on your wsgi server, such handling may already be in place (and that it uses the environment variable I mentioned)?

[Natalia Bidart]

Hello Klaas van Schelven! Thank you for taking the time to create this ticket.

I have reviewed both linked docs and I don't necessarily agree with this sentence from your report:

"it seems this is an absolutely required setting to get is_secure working correctly when behind a proxy."

To me, the docs clearly says that this *may* be necessary, in cases where your proxy *may* be swallowing the https from the original request. Then it says how, depending on how your app communicates with the proxy, is_secure *may* always be True or False, and not accounting for the original inbound request.

Because of the above, I'll be closing the ticket accordingly, but please note that we always welcome docs improvements to help future readers. So, if you want to propose a PR with a concrete suggestion about what clarification/example you would add, please re-open this ticket and we will happily review it to re-triage this report.

Thanks again!

[Klaas van Schelven]

I don't think I've made myself clear. you may read the first sentence of my issue-report as:

Looking at the documentation of ​SECURE_PROXY_SSL_HEADER it seems this is an absolutely required setting to get is_secure working correctly when behind a proxy and this proxy communicates with the backend server over a different protocol as it uses to communicate with the end-user.

That is, I understand the part of the docs where it says the proxy *may* be swallowing https perfectly well... and I agree it's correct.

My issue is with what follows: I don't see any indication in the docs that if such swallowing happens, things could still magically work out. I gave one such path: inspecting ​wsgi.url_scheme by Django, and setting it by Gunicorn.

Having said that... I've said what I wanted to say here; perhaps it will be useful to others in the future.

[Natalia Bidart]

Thank you Klaas for the further clarification, I know understand your original report.

I'm not sure how we could include the example you provided into the docs without providing a false sense of "everything will be alright" implication. There have been multiple conversations around this, the most recent I can remember is ​this one, where Carlton seems to imply that SECURE_PROXY_SSL_HEADER is preferred over setting environ["wsgi.url_scheme"] = "https".

In any case, I agree that this ticket can server as a good extra search results to understand the issue at hand.

[Klaas van Schelven]

I'm not sure I'm providing an example to be included in the docs TBH, and I think Carlton's post is about yet another case scenario, namely that where you're not able to control the headers the proxy is sending you.

[Carlton Gibson]

I raised a related discussion the Forum a while back about whether we need ​an easier control for the request's is_secure() method. It's not clear there's a consensus there as yet.

I think getting into WSGI details in the Django docs is not a good idea. Wrapping the WSGI application is available, but it's not something we want to point at too heavily IMO.

[Klaas van Schelven]

think getting into WSGI details in the Django docs is not a good idea

agreed, but the "Django part" would be clarifying that Django does look at that environment variable. The current docs for SECURE_PROXY_SSL_HEADER don't point to that at all, even though it's the other of the 2 ways in which is_secure is determined.

I raised a related discussion the Forum

There is indeed no consensus on that although you have my +1 now