CSRF troubleshooting

CSRF protection is a security feature in Django that helps prevent Cross-Site Request Forgery attacks. Bugsink uses Django’s approach to CSRF, although only a subset of Django’s features are used.

In some (rare) cases, you might run into issues with CSRF protection with your Bugsink installation. This article will help you troubleshoot these issues. The most common cause suspect is a reverse proxy misconfiguration.

Before diving into particular error messages, a double-check of your reverse proxy’s headers is a good idea.

Debugging error messages

Bugsink comes with verbose CSRF middleware, and associated error-template pre-installed. This means that when a CSRF error occurs, you will see a detailed error message that contains information about the headers that Django received.

Typically you’ll have to fix your reverse proxy’s configuration to pass the correct headers to Django. Which exact headers are needed depends on your reverse proxy, but the error message will tell you which headers Django received and you can use that information to figure out what’s going wrong.

For a full explanation of the error messages, see the verbose CSRF middleware documentation.

Note that in Bugsink, it is never needed to set CSRF_TRUSTED_ORIGINS: this setting is for the case where the origin of a request is not the same as the host of the site, but the request is still trusted. Bugsink makes no such requests.

Advanced Debugging tools

If the above error messages don’t help you, or if you want to know more about the CSRF checks that are performed, you can use the CSRF debugging tool that is built into Bugsink.

For security reasons, this tool is disabled by default. To enable it, set the DEBUG_CSRF variable to True.

Once you’ve done that, and restarted your server, the tool is available at https://your.bugsink/debug/csrf/

You’ll be greeted with a big button to press. Do it to get your debug info.

CSRF Debug Screen — Screenshot of CSRF debug screen

The process of using this information is similar to that of the verbose CSRF error messages, but in the tool you have all the information in a single table.