AcegiSecurity Plugin - v0.2.1

Added by Burt Beckwith, last edited by Burt Beckwith on Apr 24, 2008  (view change)

Acegi Plugin

Integrate Acegi Security(Spring Security) to your Grails application.

Description

Main concept for this plugin is provide Simple Security.

Implementation Overview

  • Acegi Security (Spring Security) libs
  • Controller for Login and Logout.
  • Taglibs and Service for Security.
  • creates Acegi Configuration by "doWithSpring".
  • add Filter to web.xml by "doWithWebDescriptor".

Download

Quick Start

This section shows you how to install the plugin swiftly and generate some useful interfaces according to your favour.

Quick Start
create new grails app.
# grails create-app some_app
# cd some_app
install acegi-0.2.1 plugin.
# grails install-plugin _path_to_/grails-acegi-0.2.1.zip
Setup acegi plugin
# grails create-auth-domains AuthUser Role
this will create domains and setup AcegiConfig.
(without args domains name will be Person&Authority)

if you need some management pages.
# grails generate-manager
this command generates CRUD for Domains.
# grails generate-registration
(this command generates registration controller and views)

Run your grails app.
# grails run-app

1. at first, add role (team or authority) 'user'.
http://localhost:8080/some_app/role
2. add user or register.
http://localhost:8080/some_app/user
http://localhost:8080/some_app/register
3. add request map
http://localhost:8080/some_app/requestmap

Install plugin

In your grails app, enter grails install-plugin acegi
(or grails install-plugin PATH_TO_WHERE_YOU_DOWNLOADED_/grails-acegi-0.2.1.zip)

# cd your_app
# grails install-plugin acegi
-- or --
# grails install-plugin _PATH_TO_WHERE_YOU_DOWNLOADED_/grails-acegi-0.2.1.zip

If the intallation is sucessful, you should find you have three more acegi-plugin scripts available for your app, as shown below.

Setup Commands

create-auth-domains [class name for Person] [class name for Authority]

this command will create acegi domain classes into yourapp/grails-app/domain/ and your local AcegiConfig.groovy file into yourapp/grails/conf
without any option - domains name will be Person,Authority,Requestmap

# grails create-auth-domains

you can specify domain name.

# grails create-auh-domains User Role

generate-manager

To generate all the controllers and views for those acegi domains you have created previously.

generate-registration

If you would like your app to have a user registraton interface, you can have this easily by enter "grails generate-registration" from your app. By running this script you will have java mail.jar automatically downloaded to your app/lib and RegisterController and views for this installed. Please see the AcegiConfig section about how to config your email setting.

Person(AuthUser) & Authority(Role)

How to change a field name

You can change a field name of the auth domains from your local your_app/grails-conf/AcegiConfig.groovy

For example, you can change the default authority field of Authority domain to "rolename" when you change the domain name to "Role", as shown below.

authorityDomainClass="Role"
authorityField="rolename"

all properties for Person(AuthUser) & Authority(Role)

/** login user domain class name and fields */
loginUserDomainClass="AuthUser"
userName="username"
password="passwd"
enabled="enabled"
relationalAuthorities = "authorities"

/**
 * Authority domain class authority field name
 * authorityFieldInList
 */
authorityDomainClass="Role"
authorityField="authority"

Requestmap (which secure your url)

Some instruction here about Requestmap domain as it is the core for securing a url.

Using Requestmap Domain class for the request map (Dynamic mode)

you can change secured resources dynamically by using domain class

inside AcegiConfig.groovy
useRequestMapDomainClass = true
requestMapClass="Requestmap" //domain name for request map
requestMapPathField="url" //path field name
requestMapConfigAttributeField="configAttribute" // role field name

you can add url:

new Requestmap(url:"/**",configAttribute:"IS_AUTHENTICATED_ANONYMOUSLY").save()
new Requestmap(url:"/login/**",configAttribute:"IS_AUTHENTICATED_ANONYMOUSLY").save()
new Requestmap(url:"/book/**",configAttribute:"IS_AUTHENTICATED_REMEMBERED").save()
new Requestmap(url:"/book/create/**",configAttribute:"ROLE_SUPERVISOR,ROLE_ADMIN").save()

Using request map pattern in string (Static mode)

if you want to secure your app statically.
change part of AcegiConfig.groovy as shown below.

useRequestMapDomainClass = false
requestMapString = """
  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  PATTERN_TYPE_APACHE_ANT

  /login/**=IS_AUTHENTICATED_ANONYMOUSLY
  /admin/**=ROLE_USER
  /book/test/**=IS_AUTHENTICATED_FULLY
  /book/save/**=ROLE_SUPERVISOR
  /book/**=ROLE_USER,ROLE_SUPERVISOR
  /**=IS_AUTHENTICATED_ANONYMOUSLY
"""
about AuthenticatedVoter
AuthenticatedVoter  
IS_AUTHENTICATED_FULLY not remember-me and anonymously
IS_AUTHENTICATED_REMEMBERED remember-me or is fully authenticated.
IS_AUTHENTICATED_ANONYMOUSLY remember-me, OR anonymously, OR is full authentication.

Password Encoder

Setup the digest algorithm to use.
change part of AcegiConfig.groovy as shown below.

//the named Message Digest Algorithms
algorithm="MD5"
//use Base64 text ( true or false )
encodeHashAsBase64=false

Supports the named Message Digest Algorithms in the Java environment.
see http://java.sun.com/j2se/1.4.2/docs/guide/security/CryptoSpec.html#AppA

User and Resource Management

Since 0.2, we provide the custom scaffolding UI to manage the CRUD ations over the Person,Authority,Requestmap domains.Thus now, you will have all the following features ready once you run the both setup commands mentioned eariler in your app.

Functionality Description
Person(User) Management  
Create User add a new user account to the system by authorized person(e.g.admin).
Assign role(s) to a user admin can assign certain role(s) to a new user while creating it.
Password encryption the password admin created for a new user will automatically encrypted by the digest algorithm defined earlier in your AcegiConfig.groovy.
Update User an existing user's profile and assigned roles can be edited and updated by admin.
Delete User admin can delete any existing user except himself, however, an admin is able to delete another admin user. Users to delete will be automatically removed from their role groups.
   
Authority(Role) Management  
Create Role you can create a new role with arbitray name, no constaint with the prefix ROLE_ and upper case!
Update Role updating an existing role name
Delete Role deleting a role will result in removal of that role from an existing user.
   
Requestmap(Resource) Management  
Create Resource an admin is able to secure a url context within the webapp on the fly via creating a new resource, where he will assign role groups that can have access to this url.
Update Resource updating the url or role groups assigned to that url.
Delete Resource deleting a resource will remove the security policy assigned to its url before and make it public to anonymous user.
New User Registration  
user self-register users must register themselves before they can log in. An email notification will be sent to user's inbox when they register if the email function is enabled from the plugin's configure file(AcegiConfig), please see the Emai Configuration section for more details.
user edit profie where users can edit/update their profile

Reference

Configuration

Since 0.2, we provide a AcegiConfig file, where you can customize/config your acegi-plugin based on your favor. You can override default parameters by changing/adding parameters to YOUR_APP/conf/AcegiConfig.groovy file.The following is the default setting.

DefaultAcegiConfig parameters

parameter default description
loadAcegi true activate acegi filter
algorithm MD5 encryption algorithm for user's password
encodeHashAsBase64 false Base64 encryption algorithm
userLogger false set to true to enable log4j debug info
errorPage null the location of 403 error page
loginUserDomainClass Person auth user domain class name
authorityDomainClass Authority authority domain class name
useRequestMapDomainClass Requestmap request map domain name
useEmail false set to true to enable email notification for user registration

More for your local AcegiConfig

You should find this file in your app/grails-app/conf after installation and running grails create-auth-domains

logger

  • useLogger = false

Set it true to show you the log of acegi plugin. Please note you also need to add the following

log4j.logger.org.acegisecurity="off,stdout"

to your app/grails-app/conf/Config.groovy in order to make log4j work properly.

errorPage

  • errorPage = "null"
    Why not assign a page to show some more friendly error page rather than a 403 error? For example, you can create a plain gsp called Error.gsp in your app/web-app/, then set errorPage="/Error.gsp".

Email Cofiguration

In the bottom of AcegiConfig, you can find the email configuration stuff for user registration model, as shown below.

useMail = true
mailHost = "mailhost.yahoo.co.uk"
mailUsername = "yourlogin@yahoo.co.uk"
mailPassword = "yourpass"
mailProtocol = "smtp"
mailFrom = "yourlogin@yahoo.co.uk"

Taglibs

ifAllGranted

All the listed roles must be granted.

<g:ifAllGranted
role="ROLE_ADMIN,ROLE_SUPERVISOR">

ifAnyGranted

Any of the listed roles must be granted.

<g:ifAnyGranted
role="ROLE_ADMIN,ROLE_SUPERVISOR">

ifNotGranted

None of the listed roles must be granted.

<g:ifNotGranted
role="ROLE_USER">

loggedInUserInfo

<g:loggedInUserInfo
field="username"/>

isLoggedIn

<g:isLoggedIn>
content for logged in user
</g:isLoggedIn>

isNotLoggedIn

<g:isNotLoggedIn>
content for anonymous(not loggen in) user
</g:isNotLoggedIn>

Authenticate Service

mainly used from AuthorizeTagLib, it's useful in Controllers as example below:

class SimpleController {
  AuthenticateService authenticateService

  def simpleAction = {
    def principal = authenticateService.principal()
    println principal.getUsername()//get username
    println principal.getAuthorities()//get authorities
  }
}

Secure AJAX

if request includes header "X-Requested-With",
plugin returns ajax-style response.
(you need to create an ajax-style pages by your self)

ajaxHeader="X-Requested-With"
ajaxErrorPage="/login/deniedAjax" //Ajax-style response for denied
ajaxLoginFormUrl="/login/authAjax"//Ajax-style login form
//Ajax-style = part of html,xml or json

ajax security example

Service Method Security (experiment)

Secure your Service methods by using Annotation.

import org.acegisecurity.annotation.Secured;

class SomeService {
  static transactional = true
  static scope = "request"

  @Secured(["ROLE_SUPERVISOR"])
  def getSome(){
    println "getSome()"
    return "this method is for ROLE_SUPERVISOR Only"
  }
  @Secured(["ROLE_USER"])
  def doSome(){
    println "doSome() method for ROLE_USER"
    return "this method is for ROLE_USER Only"
  }
}

History

  • April 15, 2008
    • released 0.2.1
  • Nov,2007
    • added snapshot version of 0.2
  • May 5, 2007
    • upgraded to support latest Grails 0.5+
  • Mar 25, 2007
    • added fixed version for grails-0.5-SNAPSHOT - changed getController() to getArtefact("Controller", ControllerName ).
  • Feb 9, 2007
    • Fixed more for 0.4 release
    • name changed to 'AcegiSecurity Plugin' from 'Acegi on Grails Plugin'
  • Jan , 2007
    • Fixed to use sessionFactory
  • Dec 23, 2006

Authors

  • Tsuyoshi Yamamoto
  • Haotian Sun
  • Burt Beckwith
  • Stephan M. February

TODO

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.