CSRF Prevention on the Platform

The platform offers a CSRF prevention feature that adds a layer of protection against malicious CSRF attacks.

A CSRF attack leverages the fact that the authorized user has already authenticated, and that the cookie is stored in the user's browser. The CSRF prevention feature requires an additional value, a CSRF token, to be sent in the request. If the CSRF token is not present, the request is rejected as unauthorized.

This topic includes:

Checking if CSRF Is Required: Platform Settings
Operations Exempt from CSRF
Getting the CSRF Cookie Value
Sending the CSRF Token

Note: For a training exercise that walks you through setting up the CSRF token, plus a training video, see Example: Using the CSRF header.

Checking if CSRF Is Required: Platform Settings

If the platform security settings relating to CSRF are turned off, the CSRF token is not returned at login. If either of the two settings is turned on, the CSRF token is returned. It is always returned as a cookie.

In case you are not sure whether the CSRF header is required in your implementation, here are some ways you can check:

If you're a Site Admin, you can log into the Community Manager developer portal user interface and check the security settings: Admin > Settings > Security. There are two settings:
- CSRF Support for Read Requests: requires CSRF even for GET operations that don't change data.
- CSRF Support for Write Requests: requires CSRF for operations that change data (POST, PUT, and DELETE).
Run a POST, PUT, or DELETE operation in a web client such as RESTClient. If you get an HTTP 401 status code in response, you know the CSRF header is needed. If you do get a 401, check a GET operation also.
Check the platform's security settings by running the GET /api/businesses/{BusinessID}/settings operation (if you can). Include the optional parameter for business security settings: ?IncludeSecuritySettings=true. Check whether either or both of these two settings are enabled:
- ReadRequestCSRFSupport
- WriteRequestCSRFSupport

Note: If the value of one of the CSRF settings is changed, in most cases the change might take up to five minutes to take effect. This is because the job that refreshes the cache runs every five minutes. However, there is a setting that can be configured for the change to be immediate. This setting is controlled by the Site Administrator in the Akana Administration Console for the container: Configuration Categories > com.soa.atmosphere > atmosphere.config.businessSettingsCacheRefreshOnChange property can be set to true. The default is false.

Operations Exempt from CSRF

Certain operations are exempt from CSRF, regardless of the platform settings. These are GET operations which, if disabled, could interfere with the core user experience on the platform. When the platform CSRF settings are both turned on, CSRF is required for most GET operations, but not for these specific operations that are exempt.

An example is the GET /{contentpath} operation which allows users to view API documentation which is not marked as private.

For any such operations, you'll see the below note in the documentation, below the Authorization Roles/Permissions section.

Note: The CSRF header is never required for this operation, regardless of platform settings.

Getting the CSRF Cookie Value

If the Community Manager developer portal is configured to require a CSRF token, the CSRF value is generated as a result of successful login, and is sent to the browser as a cookie, along with the standard AtmoAuthToken cookie. If the AtmoAuthToken cookie is renewed, the CSRF token is renewed at the same time, using the POST /api/login/renewToken operation.

An example of the CSRF token cookie is shown below.

Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTXgu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-tjw8NIeHdH6DV7M2COAaTZA

Sending the CSRF Token

The CSRF token can be sent in any of several ways. Different ways are better in different scenarios, as shown in the table below.

This way of sending the CSRF token...	Is used in this scenario...
Custom Header	Ajax-friendly scenarios
Part name (implemented using a hidden field in the form that contains the file upload control)	Multipart/form-data messages
POST parameter	Non-Ajax client
Query parameter	Either of these: FORM with GET action and non-Ajax client Image URLs and URLs used for iframes.

An authorized app developer can get the CSRF value from the cookie, after authenticating, and can then compose and send the custom header, parameter, or part name with the request message.

The header is the X-Csrf-Token_{fedmemberID} header. If this is required, based on platform settings, the app must take the value in the Csrf-Token cookie and send it as the value for the X-Csrf-Token_{fedmemberID} header in the following scenarios (depending on which settings are enabled):

All POST operations
All PUT operations
All DELETE operations
All GET operations except those in the following services/activities:
- Content retrieval
- Resource retrieval (such as avatars)
- Login (renewing the user's token requires the CSRF header)
- Any operations that are available to anonymous users (no login required)

An example of the X-Csrf-Token_{fedmemberID} request header is shown below.

X-Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTXgu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-tjw8NIeHdH6DV7M2COAaTZA

The Csrf-Token cookie has the same timeout value as the AtmoAuthToken authorization cookie (as specified by the Site Admin; Admin > Settings > Login in the Community Manager developer portal, PUT /api/businesses/{BusinessID}/loginpolicy in the API, 30 minutes by default).

For general information about cookies used by the platform, see Cookies in the Akana API Platform.

For information about the FedmemberID that's used in the header, see IDs on the Platform.

To use the Akana API Platform API, using the custom header, when the CSRF prevention feature is in effect: