Crowd Plugin

Table of Contents

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

Description/Features

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

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

Install and Configure the Plugin

1. Install the into a Grails webapp:

grails install-plugin crowd

1. When installing, choose 'y' when asked to add the following configuration to your Grails webapp Config.groovy:

crowd {
  application.name= 'test'                                             //Replace with name of Crowd Application
  application.password= 'password'                                     //Replace with password
  application.login.url= 'http://localhost:8080/appname/login'         //Replace with your webapp login url
  crowd.crowd.server.url= 'https://crowd.example.com/crowd/services/'  //Replace with Crowd server url
}

1. 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!

1. 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:

grails create-login-view

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:

def static authenticate= true

def static authenticate = [only:['index', 'list']]

def static authenticate = [except:['index', 'list']]

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:

def static authorize = "admin"

def static authorize = ["customer", "buyer"]

def static authorize = [all:["admin"], list:["guest", "customer"]]

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

static class CrowdAuthUtils {
  static SOAPPrincipal getAuthenticatedPrincipal(request);
  // Returns the SOAPPrincipal of a currently logged-in user
  static List<String> getAuthenticatedPrincipalGroups(request);
  // Returns a List of Group names the logged-in user belongs to
  static List<String> getAuthenticatedPrincipalRoles(request);
  // Returns a List of Role names the logged-in user belongs to
  static Boolean isAuthenticated(request);
  // Returns true if a user is logged-in, false otherwise
}

static class CrowdUtils {
  getAttributeValues(SOAPEntity entity, String attribute)
  // Returns null if not found, a String if one value, or a List<String> if multiple values
}

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:

grails create-app rockstars

Install and configure the Crowd plugin.

Create the following Grails Controller:

grails create-controller home

Edit the controller with the following:

class HomeController {
  def static authenticate= false
  def static authorize= []
  def index = {
  }
}

Create a new file for the view:

<html>
    <head>
        <meta name="layout" content="main"/>
        <title>Home</title>
    </head>
    <body>
        <div class="body">
            <h1>Home</h1>
            <crowdAuth:isAuthenticated>
                <p>I am authenticated!</p>
                <p>According to Crowd:<br/>
                    My Name is: <crowdAuth:authenticatedUserInfo property="name"/><br/>
                    My Email address is: <crowdAuth:authenticatedUserInfo property="email"/><br/>
                    My Username is: <crowdAuth:authenticatedUserInfo property="username"/><br/>
                </p>
                <p>
                    <crowdAuth:ifAllGranted group="Guitarists">
                        I am a guitarist.<br/>
                    </crowdAuth:ifAllGranted>
                    <crowdAuth:ifAnyGranted group="Guitarists,Lead Singers">
                        I am either a guitarist or a Lead Singer.<br/>
                    </crowdAuth:ifAnyGranted>
                    <crowdAuth:ifAllGranted group="Guitarists,Lead Singers">
                        I am a guitarist and a Lead Singer.<br/>
                    </crowdAuth:ifAllGranted>
                    <crowdAuth:ifAllNotGranted group="Guitarists">
                        I am not a guitarist.<br/>
                    </crowdAuth:ifAllNotGranted>
                    <crowdAuth:ifAllNotGranted group="Drummers">
                        I am not a drummer.<br/>
                    </crowdAuth:ifAllNotGranted>
                    <crowdAuth:ifAllNotGranted group="Drummers,Lead Singers">
                        I am not a drummer, nor a Lead Singer.<br/>
                    </crowdAuth:ifAllNotGranted>
                    <crowdAuth:ifAnyNotGranted group="Drummers,Guitarists">
                        I am either not a drummer, or not a guitarist, or both.<br/>
                    </crowdAuth:ifAnyNotGranted>
                </p>
            </crowdAuth:isAuthenticated>
            <crowdAuth:isNotAuthenticated>
                <p>I am not authenticated! Perhaps I should <g:link controller="login">Login</g:link>.</p>
            </crowdAuth:isNotAuthenticated>
        </div>
    </body>
</html>

Start your webapp:

grails run-app

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.

Issue Tracking