Hacking Custom Authentication Providers with Grails Spring Security

The Grails Spring Security plugin totally rocks. Even though Peter wrote a fantastic chapter on it for Grails in Action, I’ve always been a bit scared of it (based on some early bad experiences with the raw acegi codebase which *was* pretty insanely complex to get going).

Anyways, I’ve had cause to revisit Spring Security for a new client project, and had some tricky corner cases to solve. In particular, the app exposes a REST API that needs a special custom security provider. The client is issued an API key when they purchase the COTS product, and (basically) a hash of this key is remoted by a rich client during the authentication process so they can access backend services. However they can also access parts of the app using a normal browser interface with a user password and standard “remember me” features.

So the trick was supporting both a custom auth mechanism for certain URLs (eg /api/**) whilst maintaining usernames and passwords for the rest of the app. Turns out that it’s all totally doable. First a disclaimer: I know next to nothing about Spring Security, so there is probably way better ways to accomplish this, so feel free to give feedback about how I could simplify all this so that future googlers can benefit. That aside, here’s my crack.

Ok. To get all this custom stuff happening you’ll need to implement a few things:

• A custom Authentication object to hold the credentials you scrape from the client’s http POST
• A custom AuthenticationProvider which checks the credentials in that Authentication object match with the ones you’ve got stored against your backend database.
• A custom SpringSecurityFilter which slips into the request pipeline all /api/** URLs and fires when it finds some credentials to use. It will need to extract out the credentials into an Authentication object, then pass it off to the AuthenticationManager which will inturn fire you custom provider.
• Plenty of brain space to hold all that complexity…

Let’s start with the easy stuff and define our custom Authentication object to hold our credentials. You really only need a custom one so that your AuthenticationProvider class can answer true to supportsClass(auth), and there’s probably good adaptors I could have subclassed. Given I’m doing it all in Groovy, it’s very concise to implement the entire interface anyways:

import org.springframework.security.*

class CustomAppTokenAuthentication implements Authentication {

	String name
	GrantedAuthority[] authorities
 	Object credentials
 	Object details
 	Object principal
 	boolean authenticated

}

Ok. We have our “holder” for the credentials that the user is going to present. I’m going to populate the credentials and principal details from the incoming http request. It’s the role of the SpringSecurityFilter to do that scraping, then fire off the AuthenticationManager‘s pipeline of AuthenticationProviders. Here’s rough crack at a custom Filter:

import org.springframework.security.ui.*
import org.springframework.security.context.*
import org.springframework.beans.factory.*
import org.springframework.context.*
import javax.servlet.*
import javax.servlet.http.*

class CustomAppTokenFilter extends SpringSecurityFilter implements InitializingBean{

	def authenticationManager
	def customProvider

	void doFilterHttp(HttpServletRequest request, HttpServletResponse response, FilterChain chain) {

		if (SecurityContextHolder.getContext().getAuthentication() == null) {

			def userId = request.getParameter("userId")
			def apiKey = request.getParameter("apiKey")
			if ( userId && apiKey ) {

				def myAuth = new CustomAppTokenAuthentication(
						name: userId,
						credentials: apiKey,
						principal: userId,
						authenticated: true
				)

				myAuth = authenticationManager.authenticate(myAuth);
				if (myAuth) {
					println "Successfully Authenticated ${userId} in object ${myAuth}"

					// Store to SecurityContextHolder
					SecurityContextHolder.getContext().setAuthentication(myAuth);
				 }
			}
		}
		chain.doFilter(request, response)
	}

	int getOrder() {
		return FilterChainOrder.REMEMBER_ME_FILTER
	}

	void afterPropertiesSet() {
		def providers = authenticationManager.providers
		providers.add(customProvider)
		authenticationManager.providers = providers
	}
}

There’s a little magic going on here in afterPropertiesSet() where I add my custom AuthenticationProvider (which is going to actually validate the token) to the existing pipeline of AuthenticationManager providers. I was hoping to do that via configuration, but couldn’t find out how. Ideas?

With all that in place, the actual logic of firing the request is pretty straightforward. If there is a userId and apiKey coming in, and the user hasn’t already been authenticated, you create your custom Authentication holder object for the credentials (contrary to what you might think, the authenticated: true attribute means “I should be inspected by an AutheticationProvider classes” NOT “the user has been authenticated with this credential”). Traps for young players.

The last piece of code we’ll need is that AuthenticationProvider to actually validate the credential. That will need to look up the user’s details in the security database. You can use the plugin’s userDetailsService to do the heavy lifting of that one. Let’s you look up the user in the database based on their user id, then gives you a handle to the underlying domain class to get any attributes you need. Here’s my rough impl:

import org.springframework.security.*
import org.springframework.security.providers.*
import org.springframework.security.userdetails.*

class CustomAppTokenAuthenticationProvider implements AuthenticationProvider {

	def userDetailsService

	Authentication authenticate(Authentication customAuth) {
		def userDetails = userDetailsService.loadUserByUsername(customAuth.principal)
		if (userDetails?.domainClass?.apiKey == customAuth.credentials) {
			customAuth.authorities = userDetails.authorities
			return customAuth
		} else {
			return null
		}
	}

	boolean supports(Class authentication) {
		return CustomAppTokenAuthentication.class.isAssignableFrom(authentication)
	}

}

At this stage I’m just comparing that the cleartext API key’s match. In the next round I’ll use a Grails codec to do the actual .encodeAsCrazyHash algo that I’ll need for the real crypto.

With all the code in place, we just need the config to wire it all together. Let’s start with the spring bean definitions for /grails-app/conf/spring/resources.groovy:

import org.codehaus.groovy.grails.plugins.springsecurity.*
import au.com.bytecode.auth.*

beans = {

	if (AuthorizeTools.securityConfig.security.active) {

		customAppTokenFilter(CustomAppTokenFilter) {
			userDetailsService = ref("userDetailsService")
			authenticationManager = ref("authenticationManager")
			customProvider = ref("customAppTokenAppTokenAuthenticationProvider")
		}

		customAppTokenAppTokenAuthenticationProvider(CustomAppTokenAuthenticationProvider) {
	   		userDetailsService = ref("userDetailsService")
		}

	}

}

I use the plugin’s AuthorizeTools class just to check that the plugin is turned on in SecurityConfig.groovy. It’s useful to be able to turn off security for some testing via that active = false flag, so I wanted to honour that setting.

The last piece of config is making sure the filter fires only for the /api/** URL Mapping. The SecurityConfig.groovy setup allow you to specify a map of URL to pipeline. I’m not sure which filters I need in addition to my custom one, so I just specify them all — you need some of them to persist your custom credential to the http session, for instance. And some to handle the anonymous user who don’t submit a token (so that your standard @Secured annotations work on the target controller). Here’s the extract:

   filterInvocationDefinitionSourceMap = [
    '/api/**': 'httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,customAppTokenFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor',
    '/**': 'JOINED_FILTERS',
	]

The JOINED_FILTERS tag means “all the standard filters”, but you can’t seem to map “/api/**” to “customAppTokenFilter,JOINED_FILTERS” which could have been nice.

Phew! That was quite a journey! As I said, if you have better ways of simplifying this process, I’m all ears. At least here’s a rough outline of how to hack together a custom authentication mechanism if your client needs one!