Skip to content

Commit

Permalink
docs: Clarify that trust of X-Fowarded-Proto is also necessary.
Browse files Browse the repository at this point in the history
Previously, `X-Forwarded-Proto` did not need to be set, and failure to
set `loadbalancer.ips` would merely result in bad IP-address
rate-limiting and incorrect access logs; after 0935d38, however,
failure to do either of those, if Zulip is deployed with `http_only`,
will lead to infinite redirect loops after login.  These are
accompanied by a misleading error, from Tornado, of:

    Forbidden (Origin checking failed - https://zulip.example.com does not match any trusted origins.): /json/events

This is most common with Docker deployments, where deployments use
another docker container, such as nginx or Traefik, to do SSL
termination.  See zulip/docker-zulip#403.

Update the documentation to reinforce that `loadbalancer.ips` also
controls trust of `X-Forwarded-Proto`, and that failure to set it will
cause the application to not function correctly.
  • Loading branch information
alexmv authored and timabbott committed Jun 23, 2023
1 parent 6c3969f commit d46279c
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 15 deletions.
9 changes: 5 additions & 4 deletions docs/overview/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,14 +192,15 @@ log][commit-log] for an up-to-date list of all changes.
- PostgreSQL 11 is no longer supported; if you are currently using it, you will
need to [upgrade PostgreSQL](../production/upgrade.md#upgrading-postgresql)
before upgrading Zulip.
- Installations that deploy Zulip behind a [reverse
proxy][reverse-proxy-docs] should make sure the proxy is configured
to set the `X-Forwarded-Proto` HTTP header; the documentation has
updated example configuration.
- Installations that deploy Zulip behind a [reverse proxy][reverse-proxy-docs]
should make sure the proxy is configured to set the `X-Forwarded-Proto` HTTP
header, and that [`loadbalancer.ips` is accurate][loadbalancer-ips] for the
reverse proxy's IP; the documentation has updated its example configurations.
- Zulip's Twitter preview integration has been disabled due to Twitter
desupporting the API that it relied on.

[reverse-proxy-docs]: ../production/deployment.md#putting-the-zulip-application-behind-a-reverse-proxy
[loadbalancer-ips]: ../production/deployment.md#configuring-zulip-to-trust-proxies

## Zulip 6.x series

Expand Down
27 changes: 16 additions & 11 deletions docs/production/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -407,17 +407,22 @@ requests from a reverse proxy as follows:
1. Finally, restart the Zulip server, using
`/home/zulip/deployments/current/scripts/restart-server`.
Note that Zulip must be able to accurately determine if its connection to the
client was over HTTPS or not; if you enable `http_only`, it is very important
that you correctly configure Zulip to trust the `X-Forwarded-Proto` header from
its proxy (see the next section), or clients may see infinite redirects.
#### Configuring Zulip to trust proxies
Before placing Zulip behind a reverse proxy, it needs to be configured
to trust the client IP addresses that the proxy reports via the
`X-Forwarded-For` header. This is important to have accurate IP
addresses in server logs, as well as in notification emails which are
sent to end users. Zulip doesn't default to trusting all
`X-Forwarded-For` headers, because doing so would allow clients to
spoof any IP address; we specify which IP addresses are the Zulip
server's incoming proxies, so we know how much of the
`X-Forwarded-For` header to trust.
Before placing Zulip behind a reverse proxy, it needs to be configured to trust
the client IP addresses that the proxy reports via the `X-Forwarded-For` header,
and the protocol reported by the `X-Forwarded-Proto` header. This is important
to have accurate IP addresses in server logs, as well as in notification emails
which are sent to end users. Zulip doesn't default to trusting all
`X-Forwarded-*` headers, because doing so would allow clients to spoof any IP
address, and claim connections were over a secure connection when they were not;
we specify which IP addresses are the Zulip server's incoming proxies, so we
know which `X-Forwarded-*` headers to trust.
1. Determine the IP addresses of all reverse proxies you are setting up, as seen
from the Zulip host. Depending on your network setup, these may not be the
Expand Down Expand Up @@ -956,8 +961,8 @@ which have more than 20k users.
#### `ips`

Comma-separated list of IP addresses or netmasks of external load balancers
whose `X-Forwarded-For` should be respected. These can be individual IP
addresses, or CIDR IP address ranges.
whose `X-Forwarded-For` and `X-Forwarded-Proto` should be respected. These can
be individual IP addresses, or CIDR IP address ranges.

### `[http_proxy]`

Expand Down

2 comments on commit d46279c

@xpac1985
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this change. I came here to add exactly this to the Changelog (because I fell for it) - good to see someone was faster, now it just has to actually show up on ReadTheDocs ;)

@alexmv
Copy link
Collaborator Author

@alexmv alexmv commented on d46279c Jun 26, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#26046 should also help point folks in the right direction as well.

Please sign in to comment.