Spring Security for a REST API

Table of Contents

1. Overview

This tutorial shows how to Secure a REST Service using Spring and Spring Security 3.1 with Java based configuration. The article will focus on how to set up the Security Configuration specifically for the REST API using a Login and Cookie approach.

2. Spring Security in the web.xml

The architecture of Spring Security is based entirely on Servlet Filters and, as such, comes before Spring MVC in regards to the processing of HTTP requests. Keeping this in mind, to begin with, a filter needs to be declared in the web.xml of the application:

<filter>
   <filter-name>springSecurityFilterChain</filter-name>
   <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<filter-mapping>
   <filter-name>springSecurityFilterChain</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

The filter must necessarily be named ‘springSecurityFilterChain’  to match the default bean created by Spring Security in the container.

Note that the defined filter is not the actual class implementing the security logic but a DelegatingFilterProxy with the purpose of delegating the Filter’s methods to an internal bean. This is done so that the target bean can still benefit from the Spring context lifecycle and flexibility.

The URL pattern used to configure the Filter is /* even though the entire web service is mapped to /api/* so that the security configuration has the option to secure other possible mappings as well, if required.

3. The Security Configuration

 

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans
   xmlns="http://www.springframework.org/schema/security"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:beans="http://www.springframework.org/schema/beans"
   xmlns:sec="http://www.springframework.org/schema/security"
   xsi:schemaLocation="
      http://www.springframework.org/schema/security 
      http://www.springframework.org/schema/security/spring-security-3.2.xsd
      http://www.springframework.org/schema/beans 
      http://www.springframework.org/schema/beans/spring-beans-4.0.xsd">

   <http entry-point-ref="restAuthenticationEntryPoint">
      <intercept-url pattern="/api/admin/**" access="ROLE_ADMIN"/>

      <form-login 
         authentication-success-handler-ref="mySuccessHandler" 
         authentication-failure-handler-ref="myFailureHandler"
      />

      <logout />
   </http>

   <beans:bean id="mySuccessHandler"
      class="org.rest.security.MySavedRequestAwareAuthenticationSuccessHandler"/>
   <beans:bean id="myFailureHandler" 
      class="org.springframework.security.web.authentication.SimpleUrlAuthenticationFailureHandler"/>

   <authentication-manager alias="authenticationManager">
      <authentication-provider>
         <user-service>
            <user name="temporary" password="temporary" authorities="ROLE_ADMIN"/>
            <user name="user" password="user" authorities="ROLE_USER"/>
         </user-service>
      </authentication-provider>
   </authentication-manager>

</beans:beans>

Most of the configuration is done using the security namespace – for this to be enabled, the schema locations must be defined and pointed to the correct 3.1 or 3.2 XSD versions. The namespace is designed so that it expresses the common uses of Spring Security while still providing hooks raw beans to accommodate more advanced scenarios.

>> Signup for my upcoming Video Course on Building a REST API with Spring 4

3.1. The <http> element

The <http> element is the main container element for HTTP security configuration. In the current implementation, it only secured a single mapping: /api/admin/**. Note that the mapping is relative to the root context of the web application, not to the rest Servlet; this is because the entire security configuration lives in the root Spring context and not in the child context of the Servlet.

3.2. The Entry Point

In a standard web application, the authentication process may be automatically triggered when the client tries to access a secured resource without being authenticated – this is usually done by redirecting to a login page so that the user can enter credentials. However, for a REST Web Service this behavior doesn’t make much sense – Authentication should only be done by a request to the correct URI and all other requests should simply fail with a 401 UNAUTHORIZED status code if the user is not authenticated.

Spring Security handles this automatic triggering of the authentication process with the concept of an Entry Point – this is a required part of the configuration, and can be injected via the entry-point-ref attribute of the <http> element. Keeping in mind that this functionality doesn’t make sense in the context of the REST Service, the new custom entry point is defined to simply return 401 whenever it is triggered:

@Component( "restAuthenticationEntryPoint" )
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint{

   @Override
   public void commence( HttpServletRequest request, HttpServletResponse response, 
    AuthenticationException authException ) throws IOException{
      response.sendError( HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized" );
   }
}

A quick sidenote here is that the 401 is sent without the WWW-Authenticate header, as required by the HTTP Spec – we can of course set the value manually if we need to.

3.3. The Login Form for REST

There are multiple ways to do Authentication for a REST API – one of the default Spring Security provides is Form Login – which uses an authentication processing filter – org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter.

The <form-login> element will create this filter and will also allow us to set our custom authentication success handler on it. This can also be done manually by using the <custom-filter> element to register a filter at the position FORM_LOGIN_FILTER – but the namespace support is flexible enough.

Note that for a standard web application, the auto-config attribute of the <http> element is shorthand syntax for some useful security configuration. While this may be appropriate for some very simple configurations, it doesn’t fit and should not be used for a REST API.

3.4. Authentication should return 200 instead of 301

By default, form login will answer a successful authentication request with a 301 MOVED PERMANENTLY status code; this makes sense in the context of an actual login form which needs to redirect after login. For a RESTful web service however, the desired response for a successful authentication should be 200 OK.

This is done by injecting a custom authentication success handler in the form login filter, to replace the default one. The new handler implements the exact same login as the default org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler with one notable difference – the redirect logic is removed:

public class MySavedRequestAwareAuthenticationSuccessHandler 
      extends SimpleUrlAuthenticationSuccessHandler {

    private RequestCache requestCache = new HttpSessionRequestCache();

    @Override
    public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, 
      Authentication authentication) throws ServletException, IOException {
        SavedRequest savedRequest = requestCache.getRequest(request, response);

        if (savedRequest == null) {
            clearAuthenticationAttributes(request);
            return;
        }
        String targetUrlParam = getTargetUrlParameter();
        if (isAlwaysUseDefaultTargetUrl() || 
          (targetUrlParam != null && 
          StringUtils.hasText(request.getParameter(targetUrlParam)))) {
            requestCache.removeRequest(request, response);
            clearAuthenticationAttributes(request);
            return;
        }

        clearAuthenticationAttributes(request);
    }

    public void setRequestCache(RequestCache requestCache) {
        this.requestCache = requestCache;
    }
}

3.5. Failed Authentication should return 401 instead of 302

Similarly – we configured the authentication failure handler – same way we did with the success handler.

Luckily – in this case, we don’t need to actually define a new class for this handler – the standard implementation – SimpleUrlAuthenticationFailureHandler – does just fine.

The only difference is that – now that we’re defining this explicitly in our XML config – it’s not going to get a default defaultFailureUrl from Spring – and so it won’t redirect.

3.6. The Authentication Manager and Provider

The authentication process uses an in-memory provider to perform authentication – this is meant to simplify the configuration as a production implementation of these artifacts is outside the scope of this post.

3.7 Finally – Authentication against the running REST Service

Now let’s see how we can authenticate against the REST API – the URL for login is /j_spring_security_check – and a simple curl command performing login would be:

curl -i -X POST -d j_username=user -d j_password=userPass
http://localhost:8080/spring-security-rest/j_spring_security_check

This request will return the Cookie which will then be used by any subsequent request against the REST Service.

We can use curl to authentication and store the cookie it receives in a file:

curl -i -X POST -d j_username=user -d j_password=userPass -c /opt/cookies.txt 
http://localhost:8080/spring-security-rest/j_spring_security_check

Then we can use the cookie from the file to do further authenticated requests:

curl -i --header "Accept:application/json" -X GET -b /opt/cookies.txt 
http://localhost:8080/spring-security-rest/api/foos

This authenticated request will correctly result in a 200 OK:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 24 Jul 2013 20:31:13 GMT

[{"id":0,"name":"JbidXc"}]

4. Maven and other trouble

5. Conclusion

This post covered the basic security configuration and implementation for a RESTful Service using Spring Security 3.1, discussing the web.xml, the security configuration, the HTTP status codes for the authentication process and the Maven resolution of the security artifacts.

The implementation of this Spring Security REST Tutorial can be downloaded as a working sample project.This is an Eclipse based project, so it should be easy to import and run as it is.

I usually post about Security on Google+ - you can follow me there:

Get My 3 Spring eBooks
There’s no “one single way” to build an app. This is one way that I found works well.
×
Build Your Web App with Spring (and quickly prototype it to 90%)

, ,

  • http://www.toptreadmillsforhome.com/ top 10 treadmills for home

    Great information, thanks for the share!

  • Ben

    The issue for me is having users inside my xml. How would you redirect the user auth to an external resource. Would you overwrite authenticationManager?

  • Eugen

    As it is mentioned in the article, the in memory authentication provider is only used because using a real provider is outside the scope of this post. Thanks for the feedback.

  • Alwold

    On the iPhone, your “follow me” button overlaps the text, so it’s hard to read. You may want to take a look… Nice article though.

  • Sigmund Lundgren

    Hmm successful auth still redirects for my, done in the spring base class. Had to comment this line in the successhandler:

    //super.onAuthenticationSuccess(request, response, authentication);

    • René Fleischhauer

      Hi Sigmund, all,

      I have the same problem…

      super.onAuthenticationSuccess(request, response, authentication) calls SimpleUrlAuthenticationSuccessHandler#handle which contains the following line

      redirectStrategy.sendRedirect(request, response, targetUrl);

      Seems to be pretty non-sense to call the super method and therefore, I also removed it. Additionally I added a response.setStatus(200) for safety purposes…

      Best,
      René

  • fadi

    Hi,

    Am having a problem in understanding one thing, how the actual login will be done. I added the configuration and when trying to access a rest method/url I get 401 error, but am unable to figure out how and where to login. can help me pleas?

    • Eugen

      Because it’s REST, there is should be no state on the server side. What that means is that the concept of login doesn’t fit the RESTful architecture – each request will contain the credentials for it to be authenticated. So, just add the correct Authentication headers and you’ll be OK. Also, if you’re looking at the github project, there is extensive testing that does that – you can take a look at that.
      Thanks.
      Eugen.

      • fadi

        Thank you for the response, but am using FF plugin and I added the Authorization header to the url, the only place fired in my code is the EntryPoint and it never enters my AuthenticationProvider. which makes wounder if am doing something wrong!

        Thanks

        • baeldung

          Not sure how you can add the header to the URL – do you mean you added the header to the request? Also, to follow some working examples, you can always clone the project from github and run the tests.

      • DropDeadFred

        If you are using the REST service through AJAX from a browser can you had the necessary Authentication headers? For example, if you are using form based authentication to your website and want to retrieve data from your REST service. I guess I must just be missing something here.

      • Branislav Vidovic

        This is the most interesting part in my opinion…. I am interested which other additional component of spring security you have extended to read request headers and build a required authentication object. Besides i had a look into your git project but in there you did not do it totally like in this post..

    • baeldung

      The article is now updated with the exact process of how to perform the login and how to use the cookie in further requests.

  • NiceFred

    Thank you for a good article about this, just what I needed!

  • Naama

    Great article!

  • Neomi

    Great article!
    But what is the login uri? Where is it defined?

  • http://profile.yahoo.com/DULVM64SMPX6Q74MRXYD4TFHPA Marc de Verdelhan

    Your article was just what I needed. But I tested your solution and it always returned a “401 Unauthorized”.
    Finally I used the following config:

    Now it’s simpler and it works fine. Could you explain why?

    Thank you.

    • baeldung

      Hey – thanks for the feedback – I updated the article and explained how exactly to authentication and then how to use the resulting cookie in further requests against the REST API – hope it helps.

  • René Fleischhauer

    Hi all,

    thanks for the tutorial. Great stuff! I have a minor question:

    I added within the element in order to customize the login url. After starting the application again the following exception occurs:

    org.springframework.beans.factory.parsing.BeanDefinitionParsingException: Configuration problem: Filter beans ” and ” have the same ‘order’ value. When using custom filters, please make sure the positions do not conflict with default filters. Alternatively you can disable the default filters by removing the corresponding child elements from and avoiding the use of .

    The problem is clear, however I’m not sure how I can avoid the use of j_spring_security_check. I’d highly appreciate any hint.

    Best,
    René

    • baeldung

      Hi – yes, using the element is a good alternative as it does keep the configuration simple – please check out the updated configuration section and the new github project for a working implementation. Thanks.

  • Thedug

    I was just checking out the github project. The security xml file is quite different from what I see here. There’s no mention of the success handler or the entry point. Is that intentional?

    It also introduces a digest authentication and references a BASIC_AUTH_FILTER, but I haven’t seen where that is defined.

    • AlexCzar

      I have the same question, where do I define injection of MySavedRequestAwareAuthenticationSuccessHandler?

  • glz

    Great article, however every time I get 401 Unauthorized, regardless sending or not valid username and password (temporary/temporary) in username or j_username and password or j_password. Tried to figure it out looking at your git project, but there seems to be a lot of other stuff, and the only authentication used in this project is Digest authentication. Did I miss something important here?

    • baeldung

      Hi – I updated the article to better explain how to perform login and how to interact with the service; I also added a specific github project to only cover this article – should be simpler to understand. Thanks.

  • bhecht

    This was very helpful.

    I as well got an 401 Unauthorized.
    After dubugging i found out the problem is at UsernamePasswordAuthenticationFilter.requiresAuthentication() which returns true only if the URI ends with /j_spring_security_check.
    I had to override this class and return true in the requiresAuthentication(), so it will work.

    • baeldung

      Hi – the article is now updated to better explain how to interact with the REST Service – in short, yes, the first request is to /j_spring_security_check – this will return the Cookie which will be used in any further requests against the service.

  • Stephane

    Hi,

    I already have in place a working form based authentication for non-REST requests with a custom provider against a legacy database table of existing administrator credentials.

    Now, I’m trying to add an authentication, for the REST requests this time.

    I wish to use the same authentication provider if possible.

    My existing setup is:

    I added another http element:

    before the previous one but it still gives me a: A universal match pattern (‘/**’) is defined before other patterns in the filter chain…

    I wonder what to do at this point.

    You’d have some tips on how to have two authentication setups, one for browser web page authentication and one for REST based ?

    Thanks for the cool article !

    • baeldung

      I suggest using two different patterns for the 2 http elements – map the rest one on /rest or something similar and the standard one to /mvc or similar. This should keep things nice and separate.

  • Franklin Antony

    “Authentication should return 200 instead of 301″ portion doesn’t work as expected. In “MySavedRequestAwareAuthenticationSuccessHandler” the super.onAuthenticationSuccess(request, response, authentication) actually triggers a redirectStrategy.sendRedirect(request, response, targetUrl) from the parent AbstractAuthenticationTargetUrlRequestHandler. Just commenting out works, but am not sure if that is expected. Any suggestions ?

    • baeldung

      Actually, the sending of the redirect should already be commented
      out: MySavedRequestAwareAuthenticationSuccessHandler.
      Please let me know if it still doesn’t work.
      Thanks. Eugen.

      • Franklin Antony

        The sending of redirect is commented out as required but the problem lies in the parent class “AbstractAuthenticationTargetUrlRequestHandler” which “SimpleUrlAuthenticationSuccessHandler” extends from. When the “super.onAuthenticationSuccess(request, response, authentication) ” is called from “MySavedRequestAwareAuthenticationSuccessHandler” it triggers “redirectStrategy.sendRedirect(request, response, targetUrl);” in the “AbstractAuthenticationTargetUrlRequestHandler”.

        I have seen in this article “http://www.petrikainulainen.net/programming/spring-framework/integration-testing-of-spring-mvc-applications-security” that the author is not calling the “super.onAuthenticationSuccess(request, response, authentication) ” and is just calling “response.setStatus(HttpServletResponse.SC_OK);”

        Regards,
        Franklin

  • kiran

    This is very helpful.But when ever login fails with bad credentials it’s returing 302 .

    And for logout too it’s returning 302.
    Shouln’t that be changed ?

  • Sebastian

    I am using a combination of form-based login and basic authentication. So the REST endpoints can be used with the users session if he has one but falls back to basic auth if no session exists. So I like your approach with the “restAuthenticationEntryPoint”. The problem however is, that according to the HTTP documentation, a HTTP 401 response must include a WWW-Authenticate header, which you are not sending. On the other hand, this is good, because it means the browser will not display a basic authentication login dialog as it would if the WWW-Authenticate header was present. While my solution now works I am thinking if there is a better solution that allows me to use basic authentication fallback but does not violate the HTTP specification.

    • Abhishek Amte

      Hello Sebastian,
      How did you configure your basic authentication to use the credentials from the form-based?

      • Sebastian

        Hello Abhishek,

        I did not. Sending WWW-Authenticate to “FormBased” is only a means to prevent the browser from showing the basic authentication login dialog, so I can implement it in HTML. You could also set it to “Foobar” or “Custom”, it just has to be different than “Basic”.

        I now have the following in my spring security:

        authenticationFailureHandler is just an instance of SimpleUrlAuthenticationFailureHandler (without any properties set).

        This allows me to login in two ways:

        1. By HTTP Basic Auth, sending a HTTP header:

        Authorization: Basic

        2. With a POST to /session:

        method: ‘POST’,
        url: ‘../rest/session’,
        data: “j_username=” + username + “&j_password=” + password,
        headers: {‘Content-Type': ‘application/x-www-form-urlencoded’ }

        • Abhishek Amte

          Thanks a lot Sebastian

    • http://www.baeldung.com/ Eugen Paraschiv

      Yes, the WWW-Authenticate header is not included as the spec requires. This is because the current solution is a hybrid between a REST API secured with Basic/Digest authentication (for example) and a form-based authentication mechanism.
      Now – setting your own custom value for WWW-Authenticate is defninitly an option but what may be better – and what I’ve been doing – is to separate the two responsibilities – the API and the UI.
      What I mean is – the REST API is secured with Basic Auth (for this example – in practice I would suggest Digest) – and that’s it. No fallback and no complexity. Now – the UI is a form-based web application – again, no additional complexity. The bridget between them is a proxy for all of the requests from the UI to the API.
      Hope that makes sense.
      Cheers,
      Eugen.

  • Pingback: Spring MVC Token Based Authentication to a REST Service – Part 2 | notesofguclu

  • Himalay

    Whenever login fails with bad credentials it’s returing 302, shouldn’t it return 401?

    • http://www.baeldung.com/ Eugen Paraschiv

      You’re right – for correct semantics, it would have to return the 401 – I updated the article and the github project – thanks for the suggestion.
      Cheers,
      Eugen.

  • Alessandro Scuderetti

    Very useful article. I’m also interesting in => How to use the “login rest” with restful @Controller that accept and response in json format?

    This: http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2002229 according to you, is ti good?

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Alessandro – a few notes on that particular article:
      – first, it doesn’t really handle authentication for a RESTful API – but instead for a more standard webapp; a REST API will have additional architectural constraints which will impact what you’ll be able to do with Spring Security
      – next – Spring Security already has all the elements necessary for authentication in place – so adding a custom controller to replace these elements is not really necessary; what’s more – using the framework will help you deal with all of the corner cases and potential vulnerabilities that you will need to keep in mind when rolling your own controller – so, without a solid reason to do so, I would stay away from doing that
      – and finally, both the framework as well as AJAX are powerful/flexible enough to do this without a custom auth controller; what I mean is – from AJAX – you can definitely handle the default (non-json) response of Spring Security if you need to; also, from Spring Security, you can hook into the authentication process and only override the success handler if you really need to return json to the client
      Hope that helps.
      Cheers,
      Eugen.

  • Richard

    Have you tried to implement this in spring security 3.2 with the java config? I’ve put most of it together, but the form does not render on accessing /login as a GET request. I wonder if anyone has had the same experience?

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Richard – everything should work fine, but just to be on the safe side, I’m going to go through the implementation again and will get back to you. Cheers,
      Eugen.

      • elysch

        Hi.

        How did you register the restAuthenticationEntryPoint using only java config?

        Thanks

        • http://www.baeldung.com/ Eugen Paraschiv

          I didn’t – there’s some XML configuration for security in the project. That being said, if you do want to only use Java config, that’s possible now with the new release. Cheers,

          Eugen.

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Richard – I checked and everything works well. The project is indeed using Spring 3.2, and some java config. However, note that the security configuration is still XML, so if that is what you meant by java config – that support is still very new and I have not integrated it into these tutorials yet. Hope this helps. Cheers,

      Eugen.

    • elysch

      Hi Richard.

      I asked this to Eugen by mistake, but it was intended for you:

      How did you register the restAuthenticationEntryPoint using only java config?

      Thanks

      • Richard

        http.exceptionHandling().authenticationEntryPoint(restAuthenticationEntryPoint())

    • http://www.baeldung.com/ Eugen Paraschiv

      I haven’t yet, no. I’ll use the java config variant at some point, but I didn’t have the chance yet. Cheers,
      Eugen.

  • OhadR

    thanks!

  • ohadr dev

    what about logout? :-)

    • http://www.baeldung.com/ Eugen Paraschiv

      Hey Ohadr – logout is indeed enabled in the Spring Security config – notice the – so you’ll be able to log out at /j_spring_security_logout. Hope this helps. Cheers,
      Eugen.