CSRF Protection

CSRF protection uses a token (called crumb in Jenkins) that is created by Jenkins and sent to the user. Any form submissions or similar action resulting in modifications, like triggering builds or changing configuration, requires that the crumb be provided. The crumb contains information identifying the user it was created for, so submissions with another user’s token would be rejected. All of this happens in the background and has no visible impact except in rare circumstances, e.g., after a user’s session expired and they logged in again.

In Manage Jenkins » Configure Global Security » CSRF Protection, administrators can configure CSRF Protection.

The Default Crumb Issuer encodes the following information in the hash used as crumb:

All of this information needs to match when a crumb is sent back to Jenkins for that submission to be considered valid.

The only supported option Enable proxy compatibility removes information about the user IP address from the token. This can be useful when Jenkins is running behind a reverse proxy and a user’s IP address as seen from Jenkins would regularly change.

Plugins may provide other crumb issuers that use other criteria to determine whether a crumb is valid. The Strict Crumb Issuer provides an alternative crumb issuer implementation that is more customizable.

Requests sent using the POST method are subject to CSRF protection in Jenkins and generally need to provide a crumb. This also applies to scripted clients that authenticate using username and password. Since the crumb includes the web session ID, clients need to do the following:

Alternatively authenticate using username and API token. Requests authenticating with an API token are exempt from CSRF protection in Jenkins.

Outdated plugins that send HTTP requests to Jenkins may not work with CSRF protection enabled. In this case, it may be necessary to disable CSRF protection temporarily.

To disable CSRF protection, set the system property hudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION to true on startup. Learn more about system properties in Jenkins.