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.

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

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:

   grails install-plugin crowd
   

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

   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
   }
   

   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:

   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

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

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

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

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"

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

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

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

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

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

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

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

You get the idea!

Issue Tracking