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

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 developer portal user interface and check the security settings: Administration > 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

Developer Portal UI: In the developer portal, the CSRF settings are available to the Site Admin on the Admin > Settings > Security page.

Back to top

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.

Back to top

If the 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 (line breaks added for display purposes).

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

Back to top

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} response header is shown below (line breaks added for display purposes).

X-Csrf-Token_acmepaymentscorp=Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969
%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58
xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTX
gu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-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 developer portal, PUT /api/businesses/{BusinessID}/loginpolicy in the API, or 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:
  1. Get the value from the Csrf-Token cookie for the authenticated developer portal user.
  2. Send the exact same value in the X-Csrf-Token_{fedmemberID} header for the request message.

Back to top

CSRF in a federation setting

In a federation setting, CSRF should be either disabled in both/all federation members or enabled in both/all federation members. If CSRF is enabled in one federation member and disabled in other, there will be issues with conflicting permission requirements.

When changing the CSRF permission setting in two or more federation members, allow five minutes after changing the setting for the cache to be refreshed on the server side.

Back to top

Related Topics