CSRF Protection

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Cross-Site Request Forgery (CSRF or XSRF) is a type of security vulnerability in web applications. Without protection from CSRF, a Jenkins user or administrator visiting some other web site would allow the operator of that site to perform actions in Jenkins as the victim.

CSRF Protection in Jenkins

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.

The documentation on this page applies to Jenkins 2.222 or newer.

Configuring CSRF Protection

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

CSRF Protection in Security

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

  • The user name that the crumb was generated for

  • The web session ID that the crumb was generated in

  • The IP address of the user that the crumb was generated for

  • A salt unique to this Jenkins instance

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.

The web session ID was added in Jenkins 2.176.2 and 2.186 to cause crumb to expire. See security advisory and upgrade guide.

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.

Working with Scripted Clients

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:

  • Send a request to the /crumbIssuer/api endpoints, requesting a crumb. Note the Set-Cookie response header.

  • For all subsequent requests, provide the crumb and the session cookie in addition to username and password.

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

Disabling CSRF Protection

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.

It is strongly recommended that CSRF protection be left enabled, including on instances operating on private, fully trusted networks.

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.