1.x Migration Guide

Migrating from ALA Auth Plugin v1.x to v2.x

v2.x of the ala-auth-plugin provides numerous benefits:

• Integration with Grails configuration mechanism
  • No longer forces the use of .properties format for external config files.
  • Provides sane defaults - fewer config lines
  • Can now provide URL patterns in Config.groovy (and since these are really part of the application this is where they should be).
• Update to Servlet 3.0 API
  • Can retrieve context path from ServletContext, no need to provide in config (unless you're using a reverse proxy on a different path?)
• Updated CAS client library
  • Solves the service URL encoding issue
  • Additional bug fixes
• AuthService returns useful types, eg a UserDetails object instead of Map<?,?>
• No Apache HTTP client 3 dependency
• Straight forward upgrade to Grails 3

However, these benefits may also require some slight adjustments to your code:

Update other plugins

Some other plugins will also require updating to the latest version, eg:

• ala-ws-plugin
• ala-bootstrap2
• ala-ws-security

AuthService return types

1. In your app, navigate to the AuthService type and run a find usage on the methods that define return types:

• UserDetails userDetails()
• UserDetails getUserForUserId(String userId, boolean includeProps = true)
• UserDetails getUserForEmailAddress(String emailAddress, boolean includeProps = true)
• Map<String, UserDetails> getAllUserNameMap()
• def getUserDetailsById(List<String> userIds, boolean includeProps = true) (This is actually a UserDetailsFromIdListResponse)

2. Check that your code doesn't expect them to return a Map or similar. Convert those that do to def or the new AuthService types.

Update properties

All CAS properties are now namespaced into security.cas. Update the following properties in your .properties files (and ala-install!)

• casServerName ⇒ security.cas.casServerName
• casServerUrlPrefix ⇒ security.cas.casServerUrlPrefix
• contextPath ⇒ security.cas.contextPath (this property is only required if the app has a reverse proxy in front on a different context path)

Remove the following properties from your .properties file (and ala-install!)

• casProperties
• casServerLoginUrl
• gateway=false (provided by default)
• security.cas.adminRole=ROLE_ADMIN (provided by default)

Move and rename the following properties to grails-app/conf/Config.groovy (and from ala-install!) in your app source code:

• uriFilterPattern ⇒ security.cas.uriFilterPattern
• uriExclusionFilterPattern ⇒ security.cas.uriExclusionFilterPattern
• authenticateOnlyIfLoggedInFilterPattern ⇒ security.cas.authenticateOnlyIfLoggedInFilterPattern

You may also wish to provide defaults for security.cas.appServerName for the development and prod environments.

Check for usage of properties in code

Do a global find for the global properties that were renamed or removed to check whether they're used in your code and if so, take appropriate action to update the code:

• casServerLoginUrl ⇒ security.cas.loginUrl
• contextPath ⇒ def grailsResourceLocator; grailsResourceLocator.contextPath
• security.cas.contextPath ⇒ def grailsResourceLocator; grailsResourceLocator.contextPath

Note: grailsResourceLocator is only available from grails 3.0. You can use request.contextPath instead.

Migrate HttpWebService usage to ala-ws-plugin

Version 1.x of the ala-auth-plugin provided a HttpWebService class for sending HTTP GET and POST requests. Now, ala-ws-plugin's WebService provides a superset of the functionality of HttpWebService, so HttpWebService has been removed from this plugin.

To migrate, simply find any usage of httpWebService and migrate it to use the webService provided by ala-ws-plugin.

Provide properties for test environment

For sanity checking, the plugin now throws an Exception if the security.cas.appServerName is not provided. This means that it must also be provided for the test environment, so to ensure integration tests can run, ensure something similar to the following exists:

environments {
    ...
    test {
        security.cas.appServerName = 'http://devt.ala.org.au:8080/'
    }
    ...
}