CSRF Protection

Overview

Cross-Site Request Forgery (CSRF) is a security vulnerability where an attacker tricks an authenticated user's browser into making unauthorized requests to a trusted application. Because browsers automatically include session cookies with eligible requests, an attacker may be able to perform actions on behalf of the user without their knowledge or consent.

One way to mitigate CSRF attacks is by configuring the SameSite attribute on your application's session cookie. Setting this attribute to Lax or Strict restricts when browsers include cookies in cross-site requests.

However, the SameSite attribute alone may not provide sufficient CSRF protection. In particular, requests originating from different subdomains of the same site are still considered same-site requests, even when they originate from different applications.

For additional protection, applications can implement the Synchronizer Token pattern, which requires each protected request to include a CSRF token that the backend server validates against the user's application session.

Synchronizer Token Pattern

The Synchronizer Token pattern protects against CSRF attacks by requiring the frontend to include a unique, unpredictable token with authenticated requests. The backend server validates this token against the value associated with the user's application session before allowing the request to proceed.

Unlike session cookies, which browsers automatically include with eligible requests, the CSRF token must be explicitly included by the frontend. An attacker generally cannot obtain the token from another origin or include it in a valid custom request header without an additional vulnerability.

For a backend server integration with Wristband, the Synchronizer Token pattern can be implemented using a CSRF token stored in the application session and a separate cookie that makes the token accessible to frontend JavaScript.

Step 1: Generate and Store the CSRF Token

After a user successfully authenticates, Wristband redirects them to your application's Callback Endpoint. As part of creating the application session, your backend server should generate a cryptographically secure random CSRF token.

The token should contain at least 128 bits (16 bytes) of randomness, encoded using a format such as hexadecimal or Base64.

Store the generated token in two locations:

1. Application Session: Store the CSRF token alongside the user's session data. For cookie-based sessions, the token is stored in the encrypted session cookie. For server-side sessions, the token is stored in the external session datastore.
2. CSRF Cookie: Create a separate cookie containing the CSRF token so frontend JavaScript can retrieve it and include it in subsequent API requests.

The CSRF cookie should be configured with the following attributes:

• HttpOnly: Must be disabled so frontend JavaScript can read the token.
• Secure: Enabled to ensure the cookie is only transmitted over HTTPS.
• SameSite: Set to Lax or Strict to restrict cross-site transmission.
• Path and Domain: Restrict the cookie to the application paths and hosts that require access to the token.

The CSRF cookie should not contain authentication credentials or other sensitive session information.

Step 2: Include the CSRF Token in API Requests

When frontend JavaScript makes an authenticated request to a protected backend API, it should read the CSRF token from the CSRF cookie and include it in a custom HTTP request header.

For example:

X-CSRF-Token: <csrf-token>

The browser automatically includes the application session cookie with eligible requests, while the frontend explicitly adds the CSRF token to the request header.

CSRF protection should be enforced for state-changing operations, such as POST, PUT, PATCH, and DELETE requests.

Step 3: Validate the CSRF Token

Before executing a protected API's business logic, your backend server should use CSRF validation middleware to verify the request.

The middleware should perform the following checks:

1. Validate the Application Session: Retrieve and validate the user's application session using the session cookie.
2. Extract the CSRF Token: Read the token from the incoming request's X-CSRF-Token header.
3. Compare CSRF Tokens: Verify that the token from the request header matches the token stored in the user's application session.
4. Allow or Reject the Request: If the tokens match, allow the request to proceed. Otherwise, reject the request with a 403 Forbidden response.

The comparison should use a constant-time comparison function where supported to avoid introducing timing side channels.

Step 4: Clear the CSRF Cookie on Logout

When the user logs out, your application's Logout Endpoint should clear the CSRF cookie along with the application session cookie.

To clear the CSRF cookie, return a Set-Cookie header that sets its Max-Age to 0 and its value to an empty string. Ensure the cookie's Path and Domain attributes match those used when it was originally created.

When a new application session is created, generate a new CSRF token rather than reusing one from a previous session.

Additional Security Considerations

When implementing CSRF protection, keep the following recommendations in mind:

• Protect State-Changing Requests: Require CSRF validation for authenticated requests that modify application state. Avoid using GET requests for state-changing operations.
• Restrict Cross-Origin Requests: If your frontend and backend are hosted on different origins, configure CORS to allow only explicitly trusted origins. Avoid broadly allowing all subdomains, particularly when some subdomains are not fully controlled by your application.
• Prevent Token Exposure: Never include CSRF tokens in URLs or application logs.
• Protect Against XSS: CSRF tokens do not protect against cross-site scripting (XSS). An attacker who can execute JavaScript within your application's origin may be able to access the CSRF token and submit authenticated requests.