CSRF protection

Cross-Site Request Forgery (CSRF) is a type of malicious exploit where unauthorized commands are transmitted from a user that the web application trusts. In a CSRF attack, an attacker tricks a victim's browser into making unwanted requests to a web application where the victim is authenticated.

For a comprehensive understanding of CSRF attacks and prevention methods, refer to the MDN Web Docs on CSRF.

Review the configuration details in the properties documentation.

caution

Disabling CSRF protection is not recommended for production environments as it leaves your application vulnerable to cross-site request forgery attacks.

How CSRF protection works in Camunda

• Token generation: A unique CSRF token is generated and stored in a secure, HTTP-only cookie named X-CSRF-TOKEN.
• Token validation: For state-changing requests (POST, PUT, DELETE, etc.), the server validates that the CSRF token in the request header X-CSRF-TOKEN matches the one in the cookie.
• Safe methods: GET, HEAD, TRACE, and OPTIONS requests are considered safe and don't require CSRF validation.

Protected vs unprotected paths

Protected paths (require CSRF token)

• /api/** – API endpoints (except specifically excluded paths)
• /v1/**, /v2/** – Versioned API endpoints
• All state-changing operations (POST, PUT, DELETE, PATCH)

Unprotected paths (no CSRF token required)

• /actuator/** – Health and monitoring endpoints
• /v2/license – Public license endpoint
• /error – Error handling
• /logout – Ends the user session
• Safe HTTP methods (GET, HEAD, OPTIONS, TRACE)

Log in with a CSRF token

To log in programmatically, fetch a CSRF token with GET /login, then send it as the X-CSRF-TOKEN header on POST /login.

POST /login requires a valid CSRF token like any other state-changing request. It is not exempt, even for a browser that does not have a session yet. This prevents an attacker-controlled page from silently logging a victim's browser into an attacker-chosen account.

A client driving login itself (a script, health check, or custom frontend) must fetch a token before submitting credentials:

1. Send a GET request to /login. The response includes the token both as an X-CSRF-TOKEN cookie and as an X-CSRF-TOKEN response header.
2. Submit POST /login with username and password. Send the token from step 1 as the X-CSRF-TOKEN request header, and send the X-CSRF-TOKEN cookie from step 1 with the request.

Omitting the header on POST /login now fails with 401/403 instead of succeeding with 204. If the request fails, fetch a new token with GET /login and retry.

Security considerations

• Always use HTTPS in production to prevent token interception.
• Consider additional security headers configured in the security settings.
• Regularly review and update the list of unprotected paths.