Is your Web API susceptible to a CSRF exploit?

Cross-site request forgery (CSRF) is a type of security exploit where a user’s web browser is tricked by a third-party site into performing actions on websites that the user is logged into. It is often a difficult attack to pull off, as it requires a number of factors to line up at once. Protecting against it requires good discipline and good design practices, especially when it comes to protecting Web APIs.

Here’s a brief example of a fictitious CSRF attack against a bank:

  1. Sally logs into her bank,, with her account number and secure password.
  2. The bank sends a cookie to her web browser, identifying her “session”, which is the period for which she’s logged in to her account. Set-Cookie: SESSIONID=a804696f-93fc-48cf-9b02-267d9ed773c0
  3. Some time later, Sally is browsing other web sites not related to her bank. A search lands her on
  4. hosts some malicious code in their web page:
    <form name="attack" enctype="text/plain"
        action="" METHOD="POST">
      <input type="hidden" name='{"from": "Savings", "to": "00302319550440", "amount": "100.00"}'>
  5. Sally’s web browser reads the web page, and executes the code on the page, which includes sending a request to her bank to transfer $100.00 out of her savings account.
  6. Sally’s browser also includes her SESSIONID cookie with the request, because it is a request to
  7. Sally’s bank sees an authorized request to transfer money come in, with a valid session cookie, from the same IP address that the session logged-in as. The transfer is authorized.

So, how do we protect against requests that come from our users, but aren’t actually performed by them?

Traditional UI Protection

In a traditional web application, where the user primarily interacts with the application server by performing link-based navigation and form-based modification actions, you’d protect against a CSRF attack by one or more of these approaches:

  • Check the Referer header of the HTTP request to ensure that requests are generated from your own site. Don’t stop reading! I know that this sounds stupid because Referer headers are easily spoofed, right? But a CSRF attack relies on tricking a user’s browser into performing actions, so it is not possible to spoof the Referer header, because you don’t control the HTTP client. (Edit: If you disagree with me, please, tell me how such an attack would work! I want to know!)
  • Embed unguessable user-specific data in every HTTP request that performs modification actions; primarily this would be HTML forms that perform POSTs. This protects against the CSRF attack because the malicious site (eg. doesn’t know the correct user-specific data to put into the POST payload. The backend server must validate that the user-specific data is correct for every POST.
    • The simplest choice for user-specific data is the user’s session ID. That is easy to validate on the server-side.
    • Bonus points: Another option is a version identifier or last-modified timestamp of the object being edited. Checking this server-side can also serve the purpose of preventing two edits of a resource at the same time from overwriting each other. Note that a version identifier would have to be unguessable for this to work, so an auto-incrementing number is not a good candidate.

Web API Protection

Protecting a Web API requires a slightly different approach, because the API won’t have an opportunity to tell it’s client, “here, send this data as well” for each request. Here are some mechanisms for protecting a Web API from a CSRF attack:

  • Don’t allow your API to be accessed with the same credentials that your interactive UI sessions use. In the example above, if the bank’s API didn’t accept a SESSIONID cookie as a valid credential, the transfer request would not have been possible.
    • Do: use an API-key based authentication, or a more sophisticated mechanism like OAuth.
    • Don’t: allow HTTP basic, digest, or NTLM authentication to your API. If Sally’s bank hadn’t accepted SESSIONID, and instead presented WWW-Authenticate: Basic realm="" in its response, Sally would’ve been prompted to enter her bank account credentials. There’s a chance any user might enter whatever is being asked for.
    • Except: HTTP authentication mechanisms are totally safe if they’re just being used to transport an API key.
  • Requiring user-specific data can also be used to mitigate API CSRF attacks, but it doesn’t work the same way as an HTML form. Instead, imagine if Sally’s bank’s API had required that the source bank account be specified as an account number, rather than an account name. The attackers at wouldn’t have been able to supply Sally’s bank account number for the transfer.
    • Partial fix:This form of protection is less effective as the attack gets more targeted. If were targeting Sally, rather than just any user wandering past their web site, they might be able to craft more specific attacks.

Hybrid API and UI Protection

If you’re protecting your UI and your API differently, then a real conundrum is presented for modern web application development. Many people want to be able to call their own API from their UI, to develop sophisticated single-page web applications and other highly interactive UIs. So, how can you allow your client-side UI code to call your API, while still protecting the API from CSRF attacks?

  • Allow your API to accept UI authentication, like the SESSIONID cookie, but require that API calls made with that form of authentication have additional security checks on them. They can either check the Referrer header, or have user-specific data inserted into the API payload.
    • Downside: This requires that your API and your UI are pretty tightly coupled, since they would share authentication mechanisms. That works just fine for a lot of projects, but it’s an architecture no-no for some people.
  • Proxy all your UI API requests through the UI to your API. The UI will perform its normal authentication of the requests, and then insert the user’s API-key into the API requests before sending it to the API implementation.
    • Bonus points: If you implement OAuth, you can make your UI have it’s own OAuth tokens for performing API requests on behalf of the user. This is a very decoupled architecture where your UI is an API integrating application no different than any other (except possibly in provisioning the OAuth token). It’s a bit architecture-astronaut-y for most applications, but there are some real benefits.


The various mechanisms for protecting against a CSRF attack aren’t particularly complex or difficult to implement. However, they require some discipline to follow. In my experience, retrofitting an application with proper CSRF protection is difficult; individual edge cases pop-up that lead to disabling protection here and there, and eventually the system is hardly protected at all.

Read more about Cross-site request forgery on Wikipedia. Thanks to pentestmonkey for their article on arbitrary-content CSRF POSTs, which is the technique that really exposes APIs to CSRF attacks.

Be Sociable, Share!

11 Comments on Is your Web API susceptible to a CSRF exploit?

  1. John Sheehan
    2013/06/17 at 10:44 am (4 years ago)

    The Referer header can be easily spoofed and should never be relied upon to guard against CSRF.

    • Mathieu Fenniak
      2013/06/17 at 11:00 am (4 years ago)

      Hi John,

      I appreciate your feedback, and thanks again for pointing out that my comments were disabled.

      How can the Referer header be spoofed during a CSRF attack? My impression is that since the attack has to proceed with a normal user-agent that the attacker has no control over, there isn’t any way to spoof the Referer header.

  2. Jonas Vestberg
    2013/06/17 at 12:59 pm (4 years ago)

    “The simplest choice for user-specific data is the user’s session ID. That is easy to validate on the server-side.”
    Rendering the session token in HTML forms will make it possible to bypass HttpOnly attribute if it is set on the session cookie. Best practice is to use a unique random token (often called anti-forgery token) for each session.

  3. Luke Cyca
    2013/06/28 at 9:30 am (4 years ago)

    The Referer header can apparently be spoofed in the browser using flash.

    Those specific vulnerabilities may be patched, but the possibility of other undiscovered browser plugin bugs makes it difficult to trust the Referer header for CSRF protection.

  4. Taylor
    2013/07/19 at 1:13 pm (4 years ago)

    IMO the Referer header SHOULD BE relied upon to prevent CSRF attacks. It should not be able to be spoofed in a CSRF scenario – if it is being spoofed a client is not implementing it properly. Standards should not be built around the idea that they might not be followed.

    That being said if I’m building a banking website I’m putting a few more security checks in 🙂 .

  5. Roger Qiu
    2013/09/25 at 7:32 pm (3 years ago)

    I like this method: Proxy all your UI API requests through the UI to your API. The UI will perform its normal authentication of the requests, and then insert the user’s API-key into the API requests before sending it to the API implementation.

    But if I was using OAuth 2 legged between the browser client to server API along with OAuth 3 legged between the browser client to the server API to the third party provider, how would this work?

    For example are you able to answer these two questions in relationship to each other?

    If the UI client (JS based) is the one that handles the oauth access tokens, who handles the auth code exchange to access tokens (should this be done completely by the UI or exchanged server to server)? And can the CSRF code be the same as the access token?

    • Roger Qiu
      2013/09/25 at 7:34 pm (3 years ago)

      And to follow up, should this access token be a query parameter, header or cookie? Perhaps not cookie since not all HTTP clients have cookies enabled.

  6. bls
    2014/06/17 at 11:50 pm (3 years ago)

    Additionally, you should only process requests with the correct MIME type.

    The example above would not work if the application only accepts “Content-Type: application/json”.

    That alone is a little bit fragile, and relies on details of SOP (Same Origin Policy). You’re right that avoiding ambient authentication in APIs (cookies, www-authenticate etc) is stronger.

  7. shankar
    2014/09/29 at 5:38 pm (2 years ago)

    Among other things, using the referrer won’t work for users whose browsers (or corporate proxies) don’t send referrers.

    Checking The Referer Header

    Although it is trivial to spoof the referer header on your own browser, it is impossible to do so in a CSRF attack. Checking the referer is a commonly used method of preventing CSRF on embedded network devices because it does not require a per-user state. This makes a referer a useful method of CSRF prevention when memory is scarce.

    However, checking the referer is considered to be a weaker from of CSRF protection. For example, open redirect vulnerabilities can be used to exploit GET-based requests that are protected with a referer check. It should be noted that GET requests should never incur a state change as this is a violation of the HTTP specification.

    There are also common implementation mistakes with referer checks. For example if the CSRF attack originates from an HTTPS domain then the referer will be omitted. In this case the lack of a referer should be considered to be an attack when the request is performing a state change. Also note that the attacker has limited influence over the referer. For example, if the victim’s domain is “” then an attacker have the CSRF exploit originate from “” which may fool a broken referer check implementation. XSS can be used to bypass a referer check.