Spring Security’s CSRF protection for REST services: the client side and the server side

Following my previous article regarding REST security, I have decided to further push my exploration of CSRF implementation in the case of web clients talking to REST services.

The example code resulting from those tests can be found on GitHub.

But first…

CSRF (Cross-Site Request Forgery) protection is important and should be mandatory for all applications with a minimum of concern about web security. The protection uses a clever trick (the Synchronizer Token Pattern) to ensure that your requests, the ones that modify stuff on the server-side, are not fakes emitted by a third party.

The Spring Security doc has a very good example of what a CSRF attack could do. Feel free to go and read it, I’ll wait…

…done? Great. Now you can see why implementing some sort of protection against those attacks is important, especially if your web application handles sensitive data.

Who are you… who, who… who, who

If your web client sends a request to the server, how can the server be sure that the request comes from the trusted client, and not from someone else?

Well one solution would be to send the identified client a random unique token, and require the client to send that same token back when sending a request to the server. This way if the server gets the same token back on the next request by the client, it knows that the client is the one he “conversed” with during the previous exchange. On the other hand, if it doesn’t get that token back then the received request is considered unsafe and must be blocked.

Most of the times this unique token is generated once per client session: while the session lasts, the exchanged CSRF token will be the same. But if needed one can generate a new token for each request (although this might create issues, as explained in this stack overflow answer).

Serving CSRF tokens

In practice, at the server side, we will let Spring Security generate the tokens for us. CSRF handling is “on” by default, so that’s taken care for us already.

In the example code, CSRF configuration happens (implicitly!) when we configure HttpSecurity as follows:

package codesandnotes.restsecurity;

import com.allanditzel.springframework.security.web.csrf.CsrfTokenResponseHeaderBindingFilter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.security.SecurityProperties;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.web.csrf.CsrfFilter;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;

@Order(SecurityProperties.ACCESS_OVERRIDE_ORDER)
public class ApplicationSecurity extends WebSecurityConfigurerAdapter {

  @Autowired
  private RESTAuthenticationEntryPoint authenticationEntryPoint;
  @Autowired
  private RESTAuthenticationFailureHandler authenticationFailureHandler;
  @Autowired
  private RESTAuthenticationSuccessHandler authenticationSuccessHandler;

  @Override
  protected void configure(AuthenticationManagerBuilder builder) throws Exception {
    builder.inMemoryAuthentication().withUser("user").password("user").roles("USER").and().withUser("admin")
        .password("admin").roles("ADMIN");
  }

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests().antMatchers("/rest/**").authenticated();
    http.exceptionHandling().authenticationEntryPoint(authenticationEntryPoint);
    http.formLogin().successHandler(authenticationSuccessHandler);
    http.formLogin().failureHandler(authenticationFailureHandler);
    http.logout().logoutSuccessUrl("/");

    // CSRF tokens handling
    http.addFilterAfter(new CsrfTokenResponseHeaderBindingFilter(), CsrfFilter.class);
  }
}

Should you want to disable CSRF’s handling by default, you can always use the following:

@Override
protected void configure(HttpSecurity http) throws Exception {
  ...
  http.formLogin().failureHandler(authenticationFailureHandler);
  http.logout().logoutSuccessUrl("/");
  
  http.csrf().disable();

  // CSRF tokens handling
  http.addFilterAfter(new CsrfTokenResponseHeaderBindingFilter(), CsrfFilter.class);
}

But really, would you leave your application unsecured? … I thought so.

Making CSRF tokens accessible

One of the key parts in the code above, since we’re dealing with REST services, not servlets, is the CsrfTokenResponseHeaderBindingFilter class which is added as a filter.

This has been originally proposed to me by Allan Ditzel. What it does is it moves the CSRF data from the HttpServletRequest object where Spring Security has placed it, into the HttpServletResponse header that is sent back to the client. This makes the CSRF token easily accessible to the web client receiving it.

On a closer look, you will see that the class’ code is obvious and effective, and full credit goes to the man that kindly made it available to us on this GitHub repo. Check it out!

Handling CSRF tokens on the client side

This “REST Security” tutorial code on GitHub is an improvement on the code I used in my previous article about securing REST-based applications. As a reminder, I was using jQuery’s AJAX to converse with a REST-based server application, requesting client authentication before he could access a protected page.

I have extended that code so that it now fully handles CSRF tokens from the server. The token last received through a header response is initially stored in a cookie. When the user sends a request to the server, the token is sent with it.

Let’s start looking at the JavaScript code that runs when the user first arrives on the index.html page. The page requires the result of a GET request to “/rest/hello”, but the access to that information requires authentication…

jQuery(document).ready(function($) {
  $.ajax({
    type: 'GET',
    url: '/rest/hello'

  }).done(function (data, textStatus, jqXHR) {
    var csrfToken = jqXHR.getResponseHeader('X-CSRF-TOKEN');
    if (csrfToken) {
      var cookie = JSON.parse($.cookie('helloween'));
      cookie.csrf = csrfToken;
      $.cookie('helloween', JSON.stringify(cookie));
    }

    $('#helloweenMessage').html(data.message);

  }).fail(function (jqXHR, textStatus, errorThrown) {
    if (jqXHR.status === 401) { // HTTP Status 401: Unauthorized
      var cookie = JSON.stringify({method: 'GET', url: '/', csrf: jqXHR.getResponseHeader('X-CSRF-TOKEN')});
      $.cookie('helloween', cookie);

      window.location = '/login.html';

    } else {
      console.error('Houston, we have a problem...');
    }
  });

On the first run the server responds with a 401 (unauthorized), which is exactly what we expect. We therefore redirect the user to a login.html page, but not before we store in a cookie the content of the CSRF header param that was sent back to us.

On the login page, the user then submits his username and password:

$('#loginform').submit(function (event) {
  event.preventDefault();

  var cookie = JSON.parse($.cookie('helloween'));
  var data = 'username=' + $('#username').val() + '&password=' + $('#password').val();
  $.ajax({
    data: data,
    headers: {'X-CSRF-TOKEN': cookie.csrf},
    timeout: 1000,
    type: 'POST',
    url: '/login'

  }).done(function(data, textStatus, jqXHR) {
    window.location = cookie.url;

  }).fail(function(jqXHR, textStatus, errorThrown) {
    console.error('Booh! Wrong credentials, try again!');
  });
});

The jQuery code submits the login details along with that CSRF  token we stored before. Assuming the credentials are right, the user is redirected to the last visited URL which was also stored in that cookie. Back to that index.html page!

The index.html page now is authorized to get the data from “/rest/hello”. On success, the code makes sure to store the CSRF token sent back by the server in the response’s header, and accessible through the jqXHR object:

$.ajax({
  type: 'GET',
  url: '/rest/hello'

}).done(function (data, textStatus, jqXHR) {
  var csrfToken = jqXHR.getResponseHeader('X-CSRF-TOKEN');
  if (csrfToken) {
    var cookie = JSON.parse($.cookie('helloween'));
    cookie.csrf = csrfToken;
    $.cookie('helloween', JSON.stringify(cookie));
  }

  $('#helloweenMessage').html(data.message);

}).fail(function (jqXHR, textStatus, errorThrown) {
  ...
});

From there the user can click on the “POST something…” button, which sends a dummy POST request to the REST services. As always, the last CSRF token retrieved from the previous response’s headers is sent with the request:

$('#postButton').on('click', function () {
  event.preventDefault();

  var cookie = JSON.parse($.cookie('helloween'));
  $.ajax({
    data: {},
    headers: {'X-CSRF-TOKEN': cookie.csrf},
    timeout: 1000,
    type: 'POST',
    url: '/rest/hellopost'
    
  }).done(function(data, textStatus, jqXHR) {
    console.info("POST succeeded!!!");

  }).fail(function(jqXHR, textStatus, errorThrown) {
    console.error('Problems when posting...');
  });
});

By now you should be able to see the pattern:

• the server sends you a token,
• the client makes a request and returns the token to it,
• the server replies and sends back another token,
• the client makes its next request and returns that second token to the server,
• etc.

Per session CSRF tokens generation

Let’s go back to the server side for a moment. In Spring Security, the CSRF tokens are generated per session. When a session starts, a CSRF token is generated. If the session changes or times out, a new CSRF token will be returned by the server.

This can be observed by looking at the console logs output by the tutorial code:

>>>>> When GET /rest/hello fails jqXHR X-CSRF-TOKEN = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c
>>>>> When GET /rest/hello fails JSESSIONID cookie = 1u5p1wygijp7pqz1ijcjpste
>>>>> When GET /rest/hello fails no restsecurity cookie was found

The first GET request fails because we’re not authenticated. A session is already granted to the client, and a CSRF token is sent back in the response. We are then redirected to the login page.

Navigated to http://localhost:8080/login.html
>>>>> At loginform submission JSESSIONID cookie = 1u5p1wygijp7pqz1ijcjpste
>>>>> At loginform submission CSRF token in cookie = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c

We submit the login form using the CSRF stored in our cookie, which comes from the previously failed attempt’s response.

>>>>> When loginform is done jqXHR X-CSRF-TOKEN = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c
>>>>> When loginform is done JSESSIONID cookie = n3vkg1rytxnnipe221dvf0sy
>>>>> When loginform is done CSRF token in cookie = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c

Once authenticated (log inform is done) we notice that we have been given a new session!
We are then redirected to the main page where that GET request is sent again.

Navigated to http://localhost:8080/
>>>>> When index document is ready JSESSIONID cookie = n3vkg1rytxnnipe221dvf0sy
>>>>> When index document is ready CSRF token in cookie = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c
>>>>> When GET /rest/hello is done jqXHR X-CSRF-TOKEN = 185bd929-20fc-4257-a036-71436ae43e51
>>>>> When GET /rest/hello is done JSESSIONID cookie = n3vkg1rytxnnipe221dvf0sy
>>>>> When GET /rest/hello is done CSRF token in cookie = 8c16d397-bbb1-4d26-a176-ca07f9ec5c0c

The GET request succeeds, but a new CSRF token is given to us! This is what we must use for our next request:

>>>>> When postButton is clicked JSESSIONID cookie = n3vkg1rytxnnipe221dvf0sy
>>>>> When postButton is clicked CSRF token in cookie = 185bd929-20fc-4257-a036-71436ae43e51

Had we used the “old” CSRF token, we would have received back a 403 (Forbidden).

Renewing your CSRFs more frequently?

Nothing prevents us from changing the rules, though. I have not tried this myself (yet!), but we could imagine forcing the generation of a new CSRF token when, for example, the user accesses a particularly sensitive section of the web application. Such as right before submitting a bank transfer? Or maybe we need the stringiest security possible for our site and we want to generate per request tokens after all!

In any case, the frequency at which we might get a new CSRF token might change.

Also, let’s not forget that a session can time out. This implies a new login process at the client side, and a new CSRF token sent by the server. We might want to make sure we don’t miss that update!

In practice we should improve the tutorial’s code to watch for new X-CSRF-TOKEN values in the response headers, after every AJAX request, and update the stored CSRF token if needed: we should assume we never know when the server decides to change the token!

Never safe enough

This post should have given you enough material to allow you to protect your REST-based application against CSRF attacks.

Please do keep in mind that security is, more than anything, an evolving playground: what is safe today might not be safe enough tomorrow. In fact I am myself constantly learning new things about security and always trying to correct my own mistakes. As such I seriously welcome any improvement that you believe could strengthen the security of what is proposed here!

Until then: take care and be safe 😉

Cheers!