(Quick Reference)

1 Introduction to the Spring Security REST plugin - Reference Documentation

Authors: Alvaro Sanchez-Mariscal

Version: 1.2.5

1 Introduction to the Spring Security REST plugin

The Spring Security REST Grails plugin allows you to use Spring Security for a stateless, token-based, RESTful authentication.

The default behaviour of Spring Security is to store the authenticated principal in the HTTP session. However, in a RESTful scenario, we need to make sure our server is stateless.

If you are writing an API that will be used by other programs, you can use OAuth for this. But if you are exposing your API for a front-end Javascript client to implement a Single Page Interface, OAuth is not an option, specially if you want to authentication end users against your own user backend (eg: LDAP). In this case, a token-based authentication may be a more suitable implementation, like the following:

The client application requests and endpoint that requires authentication, so the server responds with a 401 response.
The client redirects the user to the login form.
The user enter credentials, and the client sends a request to the authentication endpoint. The server validates credentials, and if valid, generates, stores and sends back a token to the client.
The client then stores the token internally. It will be sent on every API method request.
The client sends again a request to the protected resource, passing the token as an HTTP header.
The server validates the token, and if valid, executes the actual operation requested.

As per the REST definition, the client is transferring its state on every request so the server is truly stateless. The approach to store tokens on the server is just an alternative to use HTTP basic authentication (see FAQ) (so credentials are not passed on every request). It also helps to perform the validation step (#5 in the diagram) faster, because the tokens, and the associated principal information may be cached. Finally, storing tokens gives you the chance to decide about expiration strategies.

More information about this strategy can be found on this post by James Ward.

This plugin helps you to wire your existing Spring Security authentication mechanism, provides you with ready-to-use token generation strategies and comes prepackaged with Memcached and GORM support for token storage.