Last updated by admin 5 years ago

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. 

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'.
    2. 

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

[class name for Person] _[class name for Authority]_">

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.{excerpt:hidden=true}

generate-acegi-webtest-data ( to be added soon)

We feel Canoo webtest plugin is a nice tool to assure the quality of your webapp, thus we provide this script to generate the webtest cases to test the above generated stuff so that you know they are at least working there :-)

Note: before you can run the test, please install webtest-plugin-0.4. This script will copy the webtest classes from our templates directly to your app/webtest/tests.{excerpt}

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 

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
-http://sky.geocities.jp/acegiongrails/grails-acegi-on-grails-0.1.zip- - this version does not work anymore.

Authors

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

TODO