Now a Grails Plugin In order to have first-class integration with Grails, I have moved all the development to Codehaus. Please visit the plugin page for all the latest info.

For the Codegeist Judges For the purposes of Codegeist, I am copying the current Codehaus wiki page here. Additionally, a copy of the Grails project (containing all sources, etc.) for the plugin CODEGEIST:is attached, and a screenshot of the default login screen (woo!) is at the bottom of the page.

Crowd Plugin

Table of Contents

CODEGEIST:Crowd Plugin

• CODEGEIST:Table of Contents
• CODEGEIST:Description/Features
• CODEGEIST:Usage
  • CODEGEIST:Crowd Requirements
  • CODEGEIST:Install and Configure the Plugin
  • CODEGEIST:Secure a Grails Controller or Action
    • CODEGEIST:Authentication
    • CODEGEIST:Authorization
  • CODEGEIST:Taglibs
    • CODEGEIST:Authentication
    • CODEGEIST:Authorization
    • CODEGEIST:Crowd Utility
  • CODEGEIST:Utility Classes
• CODEGEIST:Tutorial
• CODEGEIST:Issue Tracking

Description/Features

Plugin that adds support for Atlassian Crowd authentication and authorization to a Grails webapp.

Welcome Codegeisters!

Sure, you can wire up Grails with Acegi and the new Crowd-Acegi integration APIs released with v1.3, as Katie has done here, but that is way too much work. This Grails plugin has no dependency on Acegi, and talks to Crowd directly for its authentication and authorization requirements. The plugin borrows ideas from Grails Authorize for the simple auth/auth configuration, and from Grails Acegi for a GSP taglib.

The plugin provides a Grails webapp with simple hooks for Grails controllers and actions to require authentication and authorization. Pages requiring authentication will redirect a non-authenticated user to a supplied Login controller (with a customizable view). Logouts are handled by a supplied Logout controller. Authentication is fully integrated with Crowd's single sign-on capabilities; if a user is already logged into Crowd, the user will be authenticated to the webapp automatically.

Pages requiring authorization will return to a non-authorized user a http 503 FORBIDDEN error. The logic and/or view handling that error is also fully customizable within Grails.

The plugin also provides some Grails tag libraries to manipulate views depending on: whether the user is authenticated, and whether the user is authorized, and at what level. A tag library to easily grab information about the currently authenticated user is provided. As well, a tag library is provided for easily retrieving SOAPAttribute values from a Crowd SOAPEntity.

Finally, several utility classes provide the same functionality of the tag libraries in Groovy code. This is very useful for logic written in the controller and service areas.

Usage

Achtung! This is BETA SOFTWARE. There are bound to be some issues. The plugin shouldn't eat your app, but make a backup anyway. Bug fixes welcome!

Crowd Requirements

The plugin requires an Atlassian Crowd server, running version 1.3. You will need to configure an application within Crowd. Don't forget to specify the remote IP address. That gets me every time

Install and Configure the Plugin

1. Install the into a Grails webapp:
2. When installing, choose 'y' when asked to add the following configuration to your Grails webapp Config.groovy:
   PROJECT_ROOT/grails-app/conf/Config.groovy
   A list of all the configurable options (along with the default) is listed in PROJECT_ROOT/grails-app/conf/CrowdAuthConfig.groovy.
3. When installing, choose 'y' when asked to add default internationalization messages to your Grails webapp PROJECT_ROOT/grails-app/i18n/messages.properties.

   Further localizations will be added as they are created. Submissions welcome!

4. If you are using Grails 1.0.2 (possibly earlier), this bug (fixed in 1.0.3, whenever that arrives) requires you to copy the default Login view from the Plugin to your webapp:

Secure a Grails Controller or Action

Authentication:

Authentication is defined via the static authenticate variable in your controller

A Boolean will enable or disable authentication for all actions:

An 'only' list with enable authentication only for the listed actions:

An 'except' list with enable authentication for all actions except those listed:

Authorization:

Authorization is defined via the static authorize variable in your controller

A String will require the user belong the Crowd group for all actions:

A List will require the user to belong to all listed Crowd groups for all actions:

A Map will require the user to belong to all listed Crowd groups for specified actions:

Taglibs

Authentication:

crowdAuth:isAuthenticated will render its body if the user is authenticated.
crowdAuth:isNotAuthenticated will render its body if the user is not authenticated.
crowdAuth:authenticatedUserInfo will render information from the Crowd principal speficied in a property attribute. Valid properties are: username, name (full name), firstName, lastName, displayName, email, telephoneNumber, faxNumber.

Authorization:

crowdAuth:ifAllGranted will render its body if the user belongs to all of the comma-separated Crowd group/role names specified in a group/role attribute.
crowdAuth:ifAnyGranted will render its body if the user belongs to one of the comma-separated Crowd group/role names specified in a group/role attribute.
crowdAuth:ifNotAllGranted will render its body if the user does not belong to all of the Crowd group/role names specified in a group/role attribute.
crowdAuth:ifNotAnyGranted will render its body if the user does not belong to one of the Crowd group/role names specified in a group/role attribute.

Crowd Utility:

crowd:attributeValue will retrieve the first value of the attribute specified in an attribute named attribute from a SOAPEntity supplied in an attribute named entity.

Utility Classes

There are also some utility classes which provide an API for wrestling with the internals of the plugin:

Tutorial

The tutorial below assume Crowd to have a user named George Harrison who belongs to a group called Guitarists. There should also be some other groups (which George is not a member of) called Bassists, Drummers, and Lead Singers.

Create a Grails webapp:

CODEGEIST:Install and configure the Crowd plugin.

Create the following Grails Controller:

Edit the controller with the following:

Create a new file for the view:

Start your webapp:

In your browser, from the webapp home page, click on HomeController. If you are logged into Crowd already, you have been logged into the application automatically (via Crowd's single sign-on). If not, click on the Login link to be sent to the Login screen. Try logging in. For invalid logins, the error messages are customizable in PROJECT_ROOT/grails-app/i18n/messages.properties. The default messages were copied there on installation. Once logged in, Go back to the HomeController. Note how the screen now says you're logged in and displays some information about the user.

Things to try:

• Change HomeController's authenticate variable to true. This will make the controller automatically redirect you to the Login screen if you are not authenticated.
• Change HomeController's authorize variable to a map requiring a group to which George doesn't belong. The controller will redirect you to a 503 FORBIDDEN page.
• Change some of the tags in the view. The text should be rendered only if the conditions of the tag are met.

You get the idea!

Issue Tracking