[Django] #35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme environ

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Type:
| Uncategorized
Status: new | Component:
| Uncategorized
Version: 5.1 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Looking at the documentation of
[https://docs.djangoproject.com/en/5.1/ref/settings/#secure-proxy-ssl-
header 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 [https://wsgi.readthedocs.io/en/latest/definitions.html
#envvar-wsgi.url_scheme wsgi.url_scheme].

This value is "occasionally" set, e.g. when running in the
[https://docs.gunicorn.org/en/stable/settings.html#secure-scheme-headers
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)?
--
Ticket URL: <https://code.djangoproject.com/ticket/35800>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------

Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* component: Uncategorized => HTTP handling
* resolution: => worksforme
* status: new => closed
* type: Uncategorized => Cleanup/optimization

Comment:

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!
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:1>

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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
[https://docs.djangoproject.com/en/5.1/ref/settings/#secure-proxy-ssl-

header 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:2>

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* cc: Carlton Gibson (added)

Comment:

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 [https://noumenal.es/notes/til/django/csrf-
trusted-origins/ 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:3>

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:4>

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Carlton Gibson):

I raised a related discussion the Forum a while back about whether we need
[https://forum.djangoproject.com/t/do-we-need-an-easier-toggle-for-
request-is-secure-to-be-true/20751 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:5>

[Django]

#35800: Clarify SECURE_PROXY_SSL_HEADER as it relates to the wsgi.url_scheme
environ
-------------------------------------+-------------------------------------
Reporter: Klaas van Schelven | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: HTTP handling | Version: 5.1
Severity: Normal | Resolution:
| worksforme
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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's no consensus on that though you have my +1 now
--
Ticket URL: <https://code.djangoproject.com/ticket/35800#comment:6>