The new Certification Class of Learn Spring Security is out:


Table of Contents

1. Overview

This article is focused on how to authenticate against a secure REST API that provides a RESTful User Account and Authentication Service.

2. The Goal

First, let’s go over the actors – the typical Spring Security enabled application needs to authenticate against something – that something can be:

  • a database
  • LDAP
  • a REST service

The database is the most common scenario; however, a RESTful UAA (User Account and Authentication) Service can work just as well.

For the purpose of this article, the REST UAA Service will expose a single GET operation on /authentication, which will return the Principal information required by Spring Security to perform the full authentication process.

3. The Client

Typically, a simple Spring Security enabled application would use a simple user service as the authentication source:

<authentication-manager alias="authenticationManager">
    <authentication-provider user-service-ref="customUserDetailsService" />

This would implement the and would return the Principal based on a provided username:

public class CustomUserDetailsService implements UserDetailsService {
    public UserDetails loadUserByUsername(String username) { 

When a Client authenticates against the RESTful UAA Service, working only with the username will no longer be enough – the client now needs the full credentials – both username and password – when it’s sending the authentication request to the service. This makes perfect sense, as the service itself is secured, so the request needs to contain the authentication credentials in order to be handled properly.

From the point of view or Spring Security, this cannot be done from within loadUserByUsername because the password is no longer available at that point – we need to take control of the authentication process sooner.

We can do this by providing the full authentication provider to Spring Security:

<authentication-manager alias="authenticationManager">
    <authentication-provider ref="restAuthenticationProvider" />

Overriding the entire authentication provider gives us a lot more freedom to perform custom retrieval of the Principal from the Service, but it does come with a fair bit of complexity. The standard authentication provider – DaoAuthenticationProvider – has most of what we need, so a good approach would be to simply extend it and modify only what is necessary.

Unfortunately, this is not possible, as retrieveUser – the method we would be interested in extending – is final. This is somewhat unintuitive (there is a JIRA discussing the issue) – it looks like the design intention here is simply to provide an alternative implementation which is not ideal, but not a major problem either – our RestAuthenticationProvider copy-pastes most of the implementation of DaoAuthenticationProvider and rewrites what it needs to – the retrieval of the principal from the service:

protected UserDetails retrieveUser(String name, UsernamePasswordAuthenticationToken auth){
    String password = auth.getCredentials().toString();
    UserDetails loadedUser = null;
    try {
        ResponseEntity<Principal> authenticationResponse = 
            authenticationApi.authenticate(name, password);
        if (authenticationResponse.getStatusCode().value() == 401) {
            return new User("wrongUsername", "wrongPass", 
                Lists.<GrantedAuthority> newArrayList());
        Principal principalFromRest = authenticationResponse.getBody();
        Set<String> privilegesFromRest = Sets.newHashSet(); 
        // fill in the privilegesFromRest from the Principal
        String[] authoritiesAsArray = 
            privilegesFromRest.toArray(new String[privilegesFromRest.size()]);
        List<GrantedAuthority> authorities = 
        loadedUser = new User(name, password, true, authorities);
    } catch (Exception ex) {
        throw new AuthenticationServiceException(repositoryProblem.getMessage(), ex);
    return loadedUser;

Let’s start from the beginning – the HTTP communication with the REST Service – this is handled by the authenticationApi – a simple API providing the authenticate operation for the actual service. The operation itself can be implemented with any library capable of HTTP – in this case, the implementation is using RestTemplate:

public ResponseEntity<Principal> authenticate(String username, String pass) {
   HttpEntity<Principal> entity = new HttpEntity<Principal>(createHeaders(username, pass))
   return, HttpMethod.GET, entity, Principal.class);

HttpHeaders createHeaders(String email, String password) {
    HttpHeaders acceptHeaders = new HttpHeaders() {
    String authorization = username + ":" + password;
    String basic = new String(Base64.encodeBase64
    acceptHeaders.set("Authorization", "Basic " + basic);

    return acceptHeaders;

A FactoryBean can be used to set up the RestTemplate in the context.

Next, if the authentication request resulted in an HTTP 401 Unauthorized, most likely because of incorrect credentials from the client, a principal with wrong credentials is returned so that the Spring Security authentication process can refuse them:

return new User("wrongUsername", "wrongPass", Lists.<GrantedAuthority> newArrayList());

Finally, the Spring Security Principal needs some authorities – the privileges which that particular principal will have and use locally after the authentication process. The /authenticate operation had retrieved a full principal, including privileges, so these need to be extracted from the result of the request and transformed into GrantedAuthority objects, as required by Spring Security.

The details of how these privileges are stored are irrelevant here – they could be stored as simple Strings or as a complex Role-Privilege structure – but regardless of the details, we only need to use their names to construct the GrantedAuthoritiy objects. After the final Spring Security principal is created, it is returned back to the standard authentication process:

List<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList(authoritiesAsArray);
loadedUser = new User(name, password, true, authorities);

4. Testing the Authentication Service

Writing an integration test that consumes the authentication REST service on the happy-path is straightforward enough:

public void whenAuthenticating_then200IsReceived() {
    // When
    ResponseEntity<Principal> response 
        = authenticationRestTemplate.authenticate("admin", "adminPass");

    // Then
    assertThat(response.getStatusCode().value(), is(200));

Following this simple test, more complex integration tests can be implemented as well – however, this is outside of the scope of this post.

5. Conclusion

This article explained how to authenticate against a REST API instead of doing so against a local system such as a database.

For a full implementation of a secure RESTful service which can be used as an authentication provider, check out the GitHub project.

Go deeper into Spring Security with the course:


  • West2000

    Need Some Help ….Any suggestions examples on how to handle HTTPS with Spring Rest webservice? Can RestTemplate be used for HTTPS ? I have a RESTful webservice to consume that has a HTTPS URL and am getting the following error: org.springframework.web.client.ResourceAccessException: I/O error on GET request for THE https:// site HERE :peer not authenticated; nested exception is peer not authenticated


  • Kent Johnson

    I see how the example here shows how to have an authentication provider request user details from a RESTful resource. However, is there a way for a REST web service to handle the security authentication request completely itself?

    For example, say I have a client application written in JavaScript and a server application written in Java. The client application completely handles the user experience and when any state needs to be transmitted to the server then an AJAX call is made to a RESTful resource. Is it possible to handle the security request with my REST web service? I am trying to do so now and have followed the guidance here ( though I have yet to succeed in my endeavor.

    Do you, Eugen, know of anyone who has handled authentication completely using a REST web service? My goal is to use Spring Security with a REST controller to handle authentication requests. I request all user details internally with my service layer methods and don’t have to communicate to an external REST web service for user details (for now).

    Do I sound out of my mind trying to do this all in a REST web service? Is it possible or practical to do so?

    • Hey Kent – though we went over some of this on email, I’m going to also write a bit of feedback here just for reference. First – you’re definitly not out of your mind for trying to handle this via an API – I’ve done several client implementations like this and it works just fine. There are also a few good UAA projects out there providing this out of the box.
      So – you have a few options here – one is to manage your authentication credential headers in js (there are libraries that do that) – which is simple enough and works fine, but it does open you app for some potential vulnerabilities. Another route is to put a lightweight proxy app in front of your front end – authenticate against that with a standard cookie mechanism – and have that translate and forward your requests to your REST API.
      Hope that helps. Cheers,

      • Kent Johnson

        That does help. The first version of the REST API will use a simple HTTP Basic authentication scheme by adding a “Authorization” header to the AJAX request before it is sent to the server. The next major version of the API will probably use a proxy if myself or a team member can figure out how to do a proxy soon enough. I imagine I could use the proxy to separate out the concerns of request logging and API user metering from my main REST API.

        Thanks for your help here and through email.

  • Bob Bowen

    Great series on integrating Spring Security. I’ve read all the articles and I think I have a case which is not covered by these, or any articles I have seen on the web. (Lucky me …)

    I would like to secure a REST api. I don’t want it to be stateless — I would like to have one url dedicated to login. I would like to send a JSON request to that URL, something like:

    … other fields

    Then I’d like to use Jackson to turn that JSON into an Object , named UserCredentials. (not sure how to tell Spring Security to do this …) and use that Object to authenticate.

    That’s the hard part. I guess I’ll need a custom Provider to authenticate, because just like in the above article, the typical UserDetailsService.loadUserByUsername() isn’t enough. So I thought I would just make my own custom Provider that extends AbstractUserDetailsAuthenticationProvider and implement retrieveUser(), just like you did.

    But the signature on that method — retrieveUser(String username, UsernamePasswordAuthenticationToken authentication) — requires me to use a username and UsernamePasswordAuthenticationToken.

    So my questions: how can I create a custom Provider that authenticates my UserCredentials? Do I need a custom Token that uses UserCredentials as its principal? It seems I can’t simply extend AbstractUserDetailsAuthenticationProvider … do I have to implement AuthenticationProvider directly?

    Any help you can provide is much appreciated.

    • Well, this is indeed a sort of a hybrid usecase, it it would require a deeper dive than we can do here in the comments, but you might want to read this piece – as it also covers a similar hybrid usecase. The initial authentication request is not exactly json, but after doing that and getting the cookie, you should be OK to consume it. Cheers,

  • gautham vijay

    Hi Eugen,

    Thanks for you wonderful tutorials ,It has helped a lot . i am building a app using angular js and spring security . i want to know how to redirect to different page after login based on roles . ex if the user is ROLE_user he must be redirected to user.html and if the user is ADMIN he must be redirected to admin.html . can it be done using authenticationsuccess handler and authentication failure handler . and if i am passing the credentials from angular , which method in spring security to be invoked . can you pls help me in this regard .. thanking you in advance

    • Glad you enjoyed the article Vijay.
      Here’s how to handle these redirects. Cheers,

      • gautham vijay

        thanks a lot Eugen , i have an angularjs app which sends user credential.. so is there a method which accepts and does the authentication. or if i have to create a custom authentication provider to accept it can you pls help me with it . once again thanks you are a life saver .

        • Well Vijay – first, that’s a bit of a different problem than what this article is focused on. But, also – it’s definitely not enough info to really be able to understand what’s going on.
          Feel free to reach out to me over email and tell me more about it. Cheers,

  • Joe

    I have implemented a REST API with authentication and it accesses a DB to do the verification. However in production we found that each time a client makes an initial request, they receive a 401 authentication error, despite including credentials. We troubleshooted and thought it to be a server or firewall issue but came back to the application, which after debugging we find that in the UsernamePasswordAuthenticationToken class which extends AbstractAuthenticationToken class it has ‘credentials’ assigned to variables ‘principal’ and ‘credentials’ prior to the request being made and just when starting the application in debug mode. This gives the idea that the application is perhaps caching the last known credentials or that this is hard coded somewhere and not being the original developer, we cannot find the ‘credentials’ hardcoded anywhere. Is the concept of caching applicable here and do you think this is perhaps the cause of our issue? After the initial 401 everything is fine with 200 OK until a brief lapse in activity.

    • Hey Joe,
      First, in order to properly understand what’s going on here, I’ll need to look at the actual Spring Security config (feel free to open a Github issue on the repo of this article). Especially if you can reproduce the problem on that repo.
      Now, without that info, here’s a high level suggestion. Yes, there is a UserCache involved in the AbstractUserDetailsAuthenticationProvider (if that’s the provider you’re using) – so you can have a look at that while you’re debugging.
      Finally, beyond that, even with the cache, you shouldn’t be getting the 401 with the right configuration.
      Hope that helps. Cheers,