Jenkins CSRF CRUMB

In this lesson, you will learn how to generate and use Jenkins CSRF crumb tokens to secure your Jenkins environment. Previously, we covered API tokens and REST API calls. Today, we focus on CSRF protection in Jenkins and explore how unique crumb tokens help secure requests against Cross-Site Request Forgery attacks.

Jenkins protects you by generating a unique, randomly created token (crumb) for each user session. This token is produced by hashing details such as the username, session ID, IP address, and a unique Jenkins salt. When a submission is made, these details must match for the crumb to be considered valid.

Configuring CSRF Protection

By default, CSRF protection is enabled in Jenkins. Administrators can verify the settings by navigating to Manage Jenkins > Configure Global Security. In the security configuration, look for the CSRF protection settings, as shown in the image below:

If necessary, it is possible to disable CSRF protection by setting the following system property:

hudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true

Scrolling down in the Jenkins security configuration reveals that the default crumb issuer is selected by default:

Generating and Using the Crumb Token

To securely interact with Jenkins via the REST API, follow these steps:

1. Make a POST request to the /crumbIssuer/api/json endpoint with your username and password.
2. Upon successful authentication, Jenkins returns a JSON object with:
   • The crumb token.
   • The header name (typically "Jenkins-Crumb") to be used when making subsequent requests.
   • A Set-Cookie header that contains the session cookie.
3. Include both the crumb token and the session cookie in subsequent API requests.

Retrieving the Crumb with cURL

You can use cURL to request the crumb token. The following example demonstrates how to fetch the crumb:

curl -s \
-u admin:password \
http://localhost:8080/crumbIssuer/api/json | jq

This command outputs a JSON object similar to:

{
  "_class": "hudson.security.csrf.DefaultCrumbIssuer",
  "crumb": "6286e7b759cb388daec3a4d4e4f1fcde5da95edcb779d8b9967c1239de5cff",
  "crumbRequestField": "Jenkins-Crumb"
}

curl -v -s \
-u admin:password \
http://localhost:8080/crumbIssuer/api/json

The headers will include details such as:

HTTP/1.1 200 OK
Date: Tue, 20 Aug 2024 18:56:50 GMT
X-Content-Type-Options: nosniff
X-Jenkins: 2.462.1
X-Jenkins-Session: a52c1ba5
X-Frame-Options: deny
Content-Type: application/json;charset=utf-8
Set-Cookie: JSESSIONID.ffaa3adf=node01y1zmgr6pjx6019wb8x60kmbp0384.node0; Path=/; HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Length: 163
Server: Jetty(10.0.20)

Saving Cookies for Subsequent Requests

To ensure that the session cookie is maintained in future requests, use cURL's --cookie-jar option. For example:

curl -s -u admin:password http://localhost:8080/crumbIssuer/api/json --cookie-jar /tmp/cookies | jq

This command saves the session cookies to /tmp/cookies and displays the JSON response:

{
  "_class": "hudson.security.csrf.DefaultCrumbIssuer",
  "crumb": "28791665a0a7f47ecf03510ae3b0b2695e01d3e3f2d0ba96d1d230898051059a",
  "crumbRequestField": "Jenkins-Crumb"
}

To view the saved cookies, simply run:

cat /tmp/cookies

The output may resemble:

# Netscape HTTP Cookie File
# http://curl.se/docs/http-cookies.html
#HttpOnly_localhost   FALSE   0   JSESSIONID.ffaa3adf    node0gaz40v50cbw9ta2198n7lee0385.node0

Triggering a Job with the Crumb and Cookie

Once you have the crumb token and session cookie, you can trigger a Jenkins job. Consider a parameterized pipeline job named "parameterized-pipeline-job." Use the following cURL command to send a POST request that includes the crumb header, cookie, and necessary parameters:

curl -s -u admin:password \
--cookie /tmp/cookies \
-H "Jenkins-Crumb:28791665a0a7f47ecf03510ae3b0b2695e01d3e3f2d0ba96d1d230898051059a" \
-X POST http://localhost:8080/job/parameterized-pipeline-job/buildWithParameters \
-d BRANCH_NAME=test \
-d APP_PORT=6767

After executing the command, a new build will be triggered in Jenkins, confirming that the crumb token and session cookie are correctly configured for secure REST API calls.

Alternative: Using API Tokens

Using API tokens is an alternative authentication method that bypasses CSRF protection. When you authenticate with your username and API token, the CSRF crumb mechanism is not required, simplifying your API interactions.

Conclusion

This lesson provided a step-by-step guide to understanding and using Jenkins CSRF crumb tokens. By following these best practices, you ensure that all your API interactions with Jenkins are secure. For more detailed information, refer to the Jenkins Documentation.

Happy Coding!