Table of Contents

Configuring CSRF protection

Cross-Site Request Forgery (CSRF) is an attack that forces a user to execute unwanted actions on a web application in which the user is currently authenticated. CSRF specifically targets state-changing requests, not theft of data, because the attacker cannot see the response to the forged request. With a little help of social engineering (sending a link in email or chat), an attacker can trick the users of a web application into executing actions of the attacker's choosing. If the victim is a normal user, a successful CSRF attack can force users to perform state-changing requests including transferring funds or changing their email address. If the victim is an administrative account, CSRF can compromise the entire web application.

The AES alert with the code SECU0008 is raised for a suspected CSRF attack.

Mitigating CSRF attacks

Pega Platform™ uses session tokens to mitigate the risk of CSRF attacks. Each user session is assigned one or more unique tokens. These tokens are made available to the browser for inclusion in the URL of all requests. Each request is examined for a valid token and is rejected, if either no token or an invalid one is provided. Exceptions can be configured based on the values of the HTTP Referrer header contained in the request.

Suggested approach

For Pega Platform 8.1 and later, for the CSRF settings, use the Cross-Site Request Forgery landing page instead of modifying the dynamic system settings directly.  For more information, see Enabling Cross-Site Request Forgery settings.

For Pega Platform 7 and earlier, the following settings control the behavior of CSRF prevention:

  • security/csrf/securedActivities – Specifies a list of activities to secure (comma-separated list). A request for an activity in this list must include a valid CSRF token.
  • security/csrf/securedStreams – Specifies a list of streams to secure (comma-separated list). A request for a stream in this list must include a valid CSRF token.
  • security/csrf/secureall – Use this setting when you are not securing specific activities and streams, and the securedActivities and securedStreams settings are blank or not set.
  • security/csrf/validreferers – Specifies the valid referrers values permitted in requests (comma-separated list with no spaces). If CSRF token and activity/stream validations fail, the referrer header is validated against this list. The request fails if the referrer header is not contained in the list.
  • security/csrf/mitigation – The switch used to toggle the “CSRF mitigation” feature on or off. Enable CSRF mitigation.

The following table shows example values for the configuration settings for CSRF prevention.

Setting Default setting Sample setting
security/csrf/securedActivities Blank Data-Admin-Operator-ID.AddNewOperator, PegaAccel-Task-GenerateApp.CreateAllOperatoIds, Data-Admin-.pzCreateOperator, ReloadSection,GetLocationInFlow,PegaAccel-Task-DocumentApp.pzDocumentNow,@baseclass.WBGetRuleXmlWithKeys,getCorrInsert,PegaAccel-Task-DocumentApp.pzDocumentNow, @baseclass.WBGetRuleXmlWithKeys
security/csrf/securedStreams Blank @baseclass.ActionPreviousOperator, @baseclass.Operator-MenuPassword, Operator-Profile-ChangePassword
security/csrf/validreferers Blank http://hostName:port,http://loadBalancerURL,http://baseHTMLContext,http://wpegaw7:8080/,http://mail.pega.com/
security/csrf/mitigation false true
security/csrf/secureall false true
It is better to avoid class names, because this allows for more coverage.

The secureall setting can be too restrictive and might block valid requests in some cases. The following SQL query can be used to return a list of the activities that are likely to be included in all requests. Although the list is long, it can be specified in the value of the secured Activities Dynamic System Setting.

Select distinct(pyrulename) from rulesschema.pr4_rule where pxobjclass='Rule-Obj-Activity' and PYRULEAVAILABLE in ('Yes','Final') and PYINPUTMAYSTART = 'true'

Unique token generation and verification of the referenced header in a URL

Consider the following URL:

 http://wpegaw7:8080/prweb/PRServlet/TAHJBMlezN2PlS_vY7_FYDZ_YYZfLifF*/!@ae520a0ced4965ca3b79b12289f8676b!STANDARD?pyActivity=ReloadSection&pzTransactionId=7652a16bdb6a4d64f335f83941289efd&pzFromFrame=&pzPrimaryPageName=py DisplayHarness&pyEncodedParameters=true&pzKeepPageMessages=false&BaseReference=&StreamList=pzRecentExplorer%7CRule-HTML-Section%7C%3A&bClientValidation=true&FieldError=&FormError=&pyCustomError=&PreActivity=&HeaderButtonSectionName= &inStandardsMode=true&AJAXTrackID=3&pzHarnessID=HID1388746272425
  • ae520a0ced4965ca3b79b12289f8676b – The token, which is checked by the Pega 7 Platform for validation.
  • STANDARD – The PRThread in whose context the request would be executed.
  • http://wpegaw7:8080 – The current host on which the Pega 7 Platform is deployed.

The correct configuration in this case would be:

  • http://wpega2w7:8030,http://wpega3w7:8091,http://another.host.com – For the  URLs on the allow list, referrer headers could be configured in a Dynamic System Setting.
  • TestSecuredActivityName, AnotherSecuredActivity – For the secured activities list.
  • SecuredStreamName, testStream – For the secured streams list.

Requests for static content (style sheets, JavaScript, fonts, and so on) are assumed to not be sensitive data and are therefore not subject to CSRF token validation. Performance can also be negatively affected if static content requests include CSRF tokens.

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.