---
title: CsrfFilter
description: Prevent Cross Site Request Forgery (CSRF) attacks when using cookie-based authentication, as follows:
component: pinggateway
version: 2026
page_id: pinggateway:reference:CsrfFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CsrfFilter.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  CsrfFilter-usage: Usage
  CsrfFilter-properties: Properties
  CsrfFilter-example: Example
  CsrfFilter-moreinfo: More information
---

# 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 isn't 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

```json
{
  "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](preface.html#definition-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:

  * SSO with the [SingleSignOnFilter](SingleSignOnFilter.html): Use the name of the AM session cookie. You can find more information in [Find the AM session cookie name](../gateway-guide/preface.html#am-session-cookie).

  * CDSSO with the [CrossDomainSingleSignOnFilter](CrossDomainSingleSignOnFilter.html): Use the name configured in `authCookie.name`.

  * OpenID Connect with the [AuthorizationCodeOAuth2ClientFilter](AuthorizationCodeOAuth2ClientFilter.html): Use the name of the PingGateway HTTP session cookie (default, `IG_SESSIONID`). You can find more information about the PingGateway session cookie in [admin.json](AdminHttpApplication.html).

  * SAML: Use the name of the PingGateway HTTP session cookie (default, `IG_SESSIONID`). You can find more information about the PingGateway session cookie in [admin.json](AdminHttpApplication.html).

* `"headerName"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-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](preface.html#definition-reference), optional*

  Handler to treat the request if the CSRF the token isn't 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

You can find an example of how to harden protection against CSRF attacks in [CSRF protection with PingGateway](../gateway-guide/csrf.html).

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

## More information

[org.forgerock.openig.filter.CsrfFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/CsrfFilterHeaplet.html)