NOTE: Plugin download link is currently broken

I am having challenges with release-plugin. Please download the plugin here until I can get it fixed- Warren

Summary

Integrates Grails with OpenSSO. The plugin delegates authentication and authorization to OpenSSO.It provides the following features:

• Single Sign On with OpenSSO.
• URL policy enforecement is delegated to opensso
• Grails gsp security tags can be used.
• Security methods are dynamically added to controllers

Grails OpenSSO Plugin Notes

Overview

The OpenSSO plugin allows your Grails application to use OpenSSO for authentication and authorization. The plugin provides the following functionality :

Single Sign On (SSO) with OpenSSO:

The plugin delegates logon to OpenSSO. If the user has previously authenticated to OpenSSO, the browser will present a cookie containing the SSO token. Providing the session is still valid, the user will be transparently signed on the Grails application. If the user does not have a token, the plugin redirects them to OpenSSO. After succesfull authentication, the user is then redirected back to the application.

This means that your application is not responsible for authentication. In fact, there are no logon or password screens to maintain as OpenSSO handles it for you. One of the nice benefits of this approach is that the authentication method and strength is factored out of the application. Want to use one time passwords? How about AD? No problem - just configure the authentication chain in OpenSSO. No changes to your application.

URL Policy Enforcement

The plugin provides for enforcement of URL policy using OpenSSO. This works quite nicely with Grails and it's "REST" like structure for controller URLs. So we can (for example), allow one group of users to /list controller items, and another group of users to /update or /create new items. Custom controller methods (beyond the standard CRUD methods) can use the same mechanism.

Note that this largely eliminates the need for the @Secured annotations in Grails code - since the same effect can be implemented using URL policy. This externalizes the authorization into OpenSSO - which is generally a good thing.

Controller Security Methods

The plugin injects several security methods into your controllers to provide access to the security context. Here is sampling of methods available to controllers:

isUserInRole("ROLE_MANAGER")   - true if a user belongs to the specified Role
isUserLogon()    -  true if the user is logged on (authenticated)
getGrantedAuthorities() - returns an array of Strings representing the user's Granted Authorities (Spring terminology for role names).

GSP Tags

The plugin provides access to GSP security tags. These tags can be used in your Grails view to drive the display based on the user's role or authentication status.

For example:

<g:ifNotGranted role="ROLE_MANAGERS">You are not a Manager! </g:ifNotGranted>
<g:ifAllGranted role="ROLE_MANAGERS">Congrats. You are a manager!</g:ifAllGranted>

Using the Plugin

To use the plugin, you must complete the following steps:

• Install the plugin using grails-install plugin
• Create the AMConfig.properties file to point at your OpenSSO installation
• Override any desired properties in OpenSSOConfig.groovy.
• Create the necessary policies in OpenSSO to protect your application.

Let's look at these steps in more detail.

Installing the plugin

The plugin is installed using the command:

grails install-plugin opensso

Configuring AMConfig.properties

The next step is to configure AMConfig.properties. This property file must be found at runtime by the OpenSSO client SDK (openssoclientsdk.jar) that is included with the plugin. The best place to put it is in your src/java project directory.

The primary purpose of the property file is to help the client SDK communicate with the OpenSSO server at runtime. A complete discussion of this property file is beyond the scope of this document. The following resources are a good place to find out more:

Doc Teger's blog describes the purpose of AMConfig and how to create it.

The OpenSSO docs describes the property file in detail.

There is also a sample Grails application that you can look to for guidance. Download it from here

AMConfig looks somewhat daunting, but you can leave most properties as they are. The key things the client needs to know (that will be unique to your implementation) are the URLs of the OpenSSO server, and the credentials used by the client to communicate to OpenSSO.

You will probably want to turn on debugging during development. Here is an example of how to do that:

com.iplanet.services.debug.level=message
com.iplanet.services.debug.directory=/tmp/openssoclient

Create OpenSSOConfig.groovy

Next, override any defaults in your grails-app/conf/OpenSSOConfig.groovy file. The following is taken from the sample application:

opensso {
    active = true
     anonymousUrls = ['/', '/index.gsp' , '/auth/denied.gsp', '/images/*', '/css/*']
     loginUrl = "http://myopensso.mydomain.com:8080/UI/Login"
}

Anonymous URLs can be accessed by anyone, even if they have not authenticated. These are useful for landing pages, images and css.

Create Policies in OpenSSO

The next step is to create policies in OpenSSO to protect your application. A complete discussion of policy management is outside the scope of this document (please consult the OpenSSO documentation).

Here is small example used to protect the sample application (the URLs here are going to be different in your environment). The screen shot below shows the rule definition for denying access to “Manager” resources. Note the use of the wild card for URL matching:

The subject of the policy is configured to deny access to everyone who is NOT a manager (see the screen shot below). The “exclusive” check box indicates this applies to all subjects exclusive of those specified. In this example, it is everyone who is not in the OpenSSO managers group.

Next Steps

You should now be ready to test out the plugin. When you run your application (grails-run) and browse to the first protected page, you should see your browser get re-directed to OpenSSO for logon. Once authenticated you will be re-directed back to your application.

Check out the sample application for some ideas on using GSP security tags and programmatic security. For example, the main.gsp layout file has been modified to show the users logon name in the header:

<g:isLoggedIn>
      Logged in as: <g:loggedInUsername/>
      <a href="http://opensso.my2do.com:8080/opensso/UI/Logout?goto=http://opensso.my2do.com:18080/GrailsTestOpenSSO/index.gsp">Logout</a>
 </g:isLoggedIn>

Note the use of the logout link. This performs an SSO logout and then redirects the user back to the application page.

Troubleshooting

• Turn on debug output in AMConfig.properties
• Use fully qualified domain names throughout your application and in OpenSSO. Opensso uses domain cookies to handle SSO. Trying to access “localhost” is a common source of problems. You can use “fake” dns names in your /etc/hosts file (or Windows equivalent) for development.
• You may have to set cookie encoding to “true” in AMConfig.properties (com.iplanet.am.cookie.encode=true) and in OpenSSO (Configuration->Servers and Sites->Security->Cookie). Note these two settings must be in sync with each other (if you set it on the client, you must set it on the server).

Getting Help

The OpenSSO users mailing list is a great place to get help. You can sign up at http://opensso.org . The list is archived at http://markmail.org/search/?q=opensso

Dependencies

The plugin includes the following external dependencies:

• openssoclientsdk.jar – The OpenSSO client SDK jar file
• opensso-springsecurity-xx.jar – The OpenSSO Spring 2 Security provider. This is maintained in the OpenSSO extensions project at * https://opensso.dev.java.net/public/extensions/index.html
• Spring Security – The various Spring security jar files

Acknowledgement

This plugin is based on and includes code from the Spring Security plugin.