Debian Codegraph @

docs/proxies.rst

raw
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/