7 Configuration

7.1 Plugin

7.2 Endpoint URLs

When changing the URL for the authorizationEndpointUrl or tokenEndpointUrl, you must update Spring Security Core's configuration. Using the staticRules configuration and the default configuration as an example, your grails-app/conf/Config.groovy will look like this:

grails.plugin.springsecurity.controllerAnnotations.staticRules = [
        [pattern: '/oauth/authorize',           access: "isFullyAuthenticated() and (request.getMethod().equals('GET') or request.getMethod().equals('POST'))"],
        [pattern: '/oauth/token',               access: "isFullyAuthenticated() and request.getMethod().equals('POST')"],
        ...

To change the authorizationEndpointUrl to /authorize, you will need to make the following changes in grails-app/conf/application.groovy:

grails.plugin.springsecurity.oauthProvider.authorizationEndpointUrl = '/authorize'
grails.plugin.springsecurity.controllerAnnotations.staticRules = [
        [pattern: '/authorize',                 access: "isFullyAuthenticated() and (request.getMethod().equals('GET') or request.getMethod().equals('POST'))"],
        [pattern: '/oauth/token',               access: "isFullyAuthenticated() and request.getMethod().equals('POST')"],
        ...

7.3 Token Services

7.4 Token Enhancers Configuration

If more control over the ordering of the enhancers in the chain is desired, set the tokenServices.registerTokenEnhancers option to false. The TokenEnhancerChain bean is registered under the name tokenEnhancerChain, so the plugin consumer can get a handle to it for more fine grained configuration.

This bean is aliased under the name tokenEnhancer. This is the bean that is registered with the tokenServices bean. This is done to allow customization of the registered enhancer with minimal effort. Just override the tokenEnhancer bean.

7.5 Supported Grant Types

7.6 Additional Authorization Constraints

7.7 User Approval Configuration

The auto property determines which of the three UserApprovalHandler provided by Spring OAuth will be used.

The default option is to require explicit approval for every authorization and is equivalent to setting auto to EXPLICIT:

grails.plugin.springsecurity.oauthprovider.approval.auto = UserApproval.EXPLICIT

Auto-approval based on previously issued access tokens is supported via the TokenStoreUserApprovalHandler provided by Spring OAuth and can be configured by setting auto to TOKEN_STORE:

grails.plugin.springsecurity.oauthprovider.approval.auto = UserApproval.TOKEN_STORE

Auto-approval based on prior approvals is supported via the ApprovalStoreUserApprovalHandler provided by Spring OAuth and can be configured by setting auto to APPROVAL_STORE:

grails.plugin.springsecurity.oauthprovider.approval.auto = UserApproval.APPROVAL_STORE

The plugin will configure the TokenStoreUserApprovalHandler and ApprovalStoreUserApprovalHandler to use the GORM backed TokenStore and ApprovalStore respectively.

Please consult Spring OAuth directly for more information on the usage of the TokenStore and ApprovalStore methods of auto-approval.

7.8 Default Client Configuration

7.9 Filter Chain Configuration

By default, the OAuth2 plugin will register the statelessSecurityContextPersistenceFilter in the filter chain after the securityContextPersistenceFilter provided by the Spring Security Core plugin. This is provided as a convenience for the plugin consumer, so they can remove one filter or the other to easily achieve stateful or stateless request handling. See the example below. This automatic filter registration can be disabled by setting the registerStatelessFilter configuration option to false.

The plugin registers an OAuth2AuthenticationProcessingFilter under the bean name oauth2ProviderFilter. This filter provides token authentication using the underlying token store for resource access.

The plugin registers a ClientCredentialsTokenEndpointFilter under the bean name clientCredentialsTokenEndpointFilter. This filter is responsible for authenticating the client specified in any OAuth 2.0 requests. The plugin also registers a BasicAuthenticationFilter under the bean name oauth2BasicAuthenticationFilter. This filter is responsible for authenticating the client via HTTP Basic authentication, which is the recommended method in the OAuth 2.0 specification.

Finally, the plugin registers an ExceptionTranslationFilter under the bean name oauth2ExceptionTranslationFilter. This filter is created with a NullRequestCache instance rather than the HttpSessionRequestCache instance that the Spring Security Core plugin provided ExceptionTranslationFilter is created with. Similar to the statelessSecurityContextPersistenceFilter, this filter is registered automatically by the plugin but can be disabled by setting the registerExceptionTranslationFilter configuration option to false.

The following filter chain configuration is recommended:

grails.plugin.springsecurity.filterChain.chainMap = [
        [pattern: '/oauth/token',               filters: 'JOINED_FILTERS,-oauth2ProviderFilter,-securityContextPersistenceFilter,-logoutFilter,-authenticationProcessingFilter,-rememberMeAuthenticationFilter,-exceptionTranslationFilter'],
        [pattern: '/securedOAuth2Resources/**', filters: 'JOINED_FILTERS,-securityContextPersistenceFilter,-logoutFilter,-authenticationProcessingFilter,-rememberMeAuthenticationFilter,-oauth2BasicAuthenticationFilter,-exceptionTranslationFilter'],
        [pattern: '/**',                        filters: 'JOINED_FILTERS,-statelessSecurityContextPersistenceFilter,-oauth2ProviderFilter,-clientCredentialsTokenEndpointFilter,-oauth2BasicAuthenticationFilter,-oauth2ExceptionTranslationFilter']
]

The oauth2ProviderFilter and stateful securityContextPersistenceFilter and exceptionTranslationFilter are removed from the token endpoint's filter chain. With the securityContextPersistenceFilter removed, the statelessSecurityContextPersistenceFilter will be used to ensure access token requests are stateless. Similarly, removing the exceptionTranslationFilter will allow the oauth2ExceptionTranslationFilter to take its place in the filter chain.

The securityContextPersistenceFilter and exceptionTranslationFilter are also removed from the filter chain for OAuth 2.0 resources. However, the oauth2ProviderFilter must not be removed, as this filter is responsible for authenticating the OAuth 2.0 access token included in the request.

It is recommend that filter chain(s) for non-OAuth 2.0 resources have all OAuth 2.0 specific filters removed. These include: statelessSecurityContextPersistenceFilter, oauth2ProviderFilter, clientCredentialsTokenEndpointFilter, basicAuthenticationFilter and oauth2ExceptionTranslationFilter. It is also recommended that any unnecessary filters such as the rememberMeAuthenticationFilter and authenticationProcessingFilter are removed from the filter chains for the token endpoint and OAuth 2.0 resources.

7.10 Domain Class Custom Serialization Configuration

To accommodate these users, it is possible to override the default serialization method on a case-by-case basis. The plugin provides two interfaces to accomplish.

For the additionalInformation fields:

package grails.plugin.springsecurity.oauthprovider.serialization;
import java.util.Map;
public interface OAuth2AdditionalInformationSerializer {
    Object serialize(Map<String, Object> additionalInformation);
    Map<String, Object> deserialize(Object additionalInformation);
}

For the scope field:

package grails.plugin.springsecurity.oauthprovider.serialization;
import java.util.Set;
public interface OAuth2ScopeSerializer {
    Object serialize(Set<String> scopes);
    Set<String> deserialize(Object scopes);
}

By default, the plugin registers implementations that do little more than return the argument provided to each method. The following table shows which plugin provided Spring beans implement these interfaces and how they're used:

Overriding these beans in resources.groovy will allow the plugin consumer to customize how these fields are serialized. However, this will require the affected domain class to be modified to accommodate the change. For example, let's change the AccessToken to serialized its additionalInformation as JSON String and its scope as white space delimited String.

First, modify the AccessToken class to reflect the change in the storage of these fields:

package test.oauth2
class AccessToken {
    String authenticationKey
    byte[] authentication
    String username
    String clientId
    String value
    String tokenType
    Date expiration
    String additionalInformation
    String scope
    static hasOne = [refreshToken: String]
    static constraints = {
        username nullable: true
        clientId nullable: false, blank: false
        value nullable: false, blank: false, unique: true
        tokenType nullable: false, blank: false
        expiration nullable: false
        scope nullable: false
        refreshToken nullable: true
        authenticationKey nullable: false, blank: false, unique: true
        authentication nullable: false, minSize: 1, maxSize: 1024 * 4
        additionalInformation nullable: true
    }
    static mapping = {
        version false
        scope lazy: false
    }
}

Next, implement the earlier described interfaces:

package test
import grails.plugin.springsecurity.oauthprovider.serialization.OAuth2ScopeSerializer
import org.springframework.security.oauth2.common.util.OAuth2Utils
class WhiteSpaceDelimitedStringScopeSerializer implements OAuth2ScopeSerializer {
    @Override
    Object serialize(Set<String> scopes) {
        return OAuth2Utils.formatParameterList(scopes)
    }
    @Override
    Set<String> deserialize(Object scopes) {
        return OAuth2Utils.parseParameterList(scopes)
    }
}

And:

package test
import grails.plugin.springsecurity.oauthprovider.serialization.OAuth2AdditionalInformationSerializer
import groovy.json.JsonOutput
import groovy.json.JsonSlurper
class JsonAdditionalInformationSerializer implements OAuth2AdditionalInformationSerializer {
    @Override
    Object serialize(Map<String, Object> additionalInformation) {
        JsonOutput.toJson(additionalInformation)
    }
    @Override
    Map<String, Object> deserialize(Object additionalInformation) {
        new JsonSlurper().parseText(additionalInformation as String)
    }
}

The serialize methods are guaranteed to receive a non-null argument, although they may be provided an empty collection. The deserialize methods are expected to return a non-null value.

Finally, in resources.groovy, override the appropriate beans:

import test.JsonAdditionalInformationSerializer
import test.WhiteSpaceDelimitedStringScopeSerializer
beans = {
    // Other beans here
    accessTokenAdditionalInformationSerializer(JsonAdditionalInformationSerializer)
    accessTokenScopeSerializer(WhiteSpaceDelimitedStringScopeSerializer)
}