PingGateway 2024.6

CsrfFilter

Prevent Cross Site Request Forgery (CSRF) attacks when using cookie-based authentication, as follows:

  • When a session is created or updated for a client, generate a CSRF token as a hash of the session cookie.

  • Send the token in a response header to the client, and require the client to provide that header in subsequent requests.

  • In subsequent requests, compare the provided token to the generated token.

  • If the token is not provided or can’t be validated, reject the request and return a valid CSRF token transparently in the response header.

    Rogue websites that attempt CSRF attacks operate in a different website domain to the targeted website. Because of same-origin policy, rogue websites can’t access a response from the targeted website, and cannot, therefore, access the CSRF token.

Usage

{
  "name": string,
  "type": "CsrfFilter",
  "config": {
    "cookieName": configuration expression<string>,
    "headerName": configuration expression<string>,
    "excludeSafeMethods": configuration expression<boolean>,
    "failureHandler": Handler reference
  }
}

Properties

"cookieName": configuration expression<string>, required

The name of the HTTP session cookie used to store the session ID. For example, use the following cookie names for the following processes:

"headerName": configuration expression<string>, optional

The name of the header that carries the CSRF token. The same header is used to create and verify the token.

Default: X-CSRF-Token

"excludeSafeMethods": configuration expression<boolean>, optional

Whether to exclude GET, HEAD, and OPTION methods from CSRF testing. In most cases, these methods are assumed as safe from CSRF.

Default: true

"failureHandler": Handler reference, optional

Handler to treat the request if the CSRF the token is not provided or can’t be validated. Provide an inline handler declaration, or the name of a handler object defined in the heap.

Although PingGateway returns the CSRF token transparently in the response header, this handler cannot access the CSRF token.

Default: Handler that generates HTTP 403 Forbidden.

Example

For an example of how to harden protection against CSRF attacks, see CSRF protection.

{
  "name": "CsrfFilter-1",
  "type": "CsrfFilter",
  "config": {
    "cookieName": "openig-jwt-session",
    "headerName": "X-CSRF-Token",
    "excludeSafeMethods": true
  }
}