| 1 |
Proxies and HTTPS |
| 2 |
================= |
| 3 |
|
| 4 |
Running a secure HTTPS website is important, but encrypting and decrypting |
| 5 |
HTTPS traffic is computationally expensive. Many people running large-scale |
| 6 |
websites (including `Heroku`_) use a `TLS termination proxy`_ to reduce load |
| 7 |
on the HTTP server. This works great, but means that the webserver running |
| 8 |
your Flask application is actually speaking HTTP, not HTTPS. |
| 9 |
|
| 10 |
As a result, Flask-Dance can get confused, and generate callback URLs |
| 11 |
that have an ``http://`` scheme, instead of an ``https://`` scheme. |
| 12 |
This is bad, because OAuth requires that all connections use HTTPS for |
| 13 |
security purposes, and OAuth providers will reject requests that suggest |
| 14 |
a callback URL with a ``http://`` scheme. |
| 15 |
|
| 16 |
When you proxy the request from a `TLS termination proxy`_, probably your |
| 17 |
load balancer, you need to ensure a few headers are set/proxied correctly |
| 18 |
for Flask to do the right thing out of the box: |
| 19 |
|
| 20 |
* ``Host``: preserve the Host header of the original request |
| 21 |
* ``X-Real-IP``: preserve the source IP of the original request |
| 22 |
* ``X-Forwarded-For``: a list of IP addresses of the source IP and any |
| 23 |
HTTP proxies we've been through |
| 24 |
* ``X-Forwarded-Proto``: the protocol, http or https, that the request |
| 25 |
came in with |
| 26 |
|
| 27 |
In 99.9% of the cases the `TLS termination proxy`_ will be configured to |
| 28 |
do the right thing by default and any well-behaved Flask application will |
| 29 |
work out of the box. However, if you're accessing the WSGI environment |
| 30 |
directly, you will run into trouble. Don't do this and instead use the |
| 31 |
functions provided by Werkzeug's :mod:`~werkzeug.wsgi` module or Flask's |
| 32 |
:attr:`~flask.request` to access things like a ``Host`` header. |
| 33 |
|
| 34 |
If your Flask app is behind a TLS termination proxy, and you need to make |
| 35 |
sure that Flask is aware of that, check Flask's documentation for |
| 36 |
:external:doc:`how to deploy a proxy setup <deploying/proxy_fix>`. |
| 37 |
|
| 38 |
Please read it and follow its instructions. This is not unique to |
| 39 |
Flask-Dance and there's nothing to configure on Flask-Dance's side |
| 40 |
to solve this. It's also worth noting you might wish to set Flask's |
| 41 |
:data:`PREFERRED_URL_SCHEME`. |
| 42 |
|
| 43 |
.. _TLS termination proxy: https://en.wikipedia.org/wiki/TLS_termination_proxy |
| 44 |
.. _Heroku: https://www.heroku.com/ |