(Quick Reference)

4 Security API - Reference Documentation

Authors: Marc Palmer (marc@grailsrocks.com), Stéphane Maldini (smaldini@vmware.com)

Version: 1.0.RC3

4 Security API

The Security API provides common security related functionality so that plugins and in some cases applications no longer need to be tied to a specific security implementation.

It is deliberately minimal to place few requirements on implementations.

It is not intended to be a complete security abstraction, but "just enough" for the needs of most applications and plugins that do not require advanced security manipulation - which will likely always require direct knowledge of the underlying provider.

This API provides the most basic security features to enable this interoperability, using a bridging interface that security plugins must implement to actually provide these services.

Security plugins must implement the "provider" bean - out of the box there is no security implementation.

Dynamic methods

These methods and properties are added to Services, Controllers, TagLibs and Domain Classes:

  • securityIdentity - The string used to identify the current logged in user. Typically a user id, user name or email address. The nature of this value is dependent on your security implementation
  • securityInfo - The object representing the current logged in user's information.
  • userHasAnyRole - test if the current user has any of the roles
  • userHasAllRoles - test if the current user has all of the roles
  • userIsAllowed - test if the current user has a specified permission on an object
  • withUser - run a section of code as another user

See the reference guide for Security Properties and Security Methods for further details on these.

All of these features and more can be accessed by any code in your application by using the grailsSecurity bean.


Here's an example of some of the security tags available:

<s:info property="email"/>
<s:ifPermitted role="ROLE_ADMIN">
<s:ifNotPermitted role="ROLE_ADMIN">
<a href="${s.createLoginLink()}">Log in</a>
<a href="${s.createLogoutLink()}">Log out</a>
<a href="${s.createSignupLink()}">Sign up</a>

See the Tags Security reference section for details.

grailsSecurity bean

The Security bean provides access to all the basic security functions. These are passed through to the security bridge implementation.

This includes methods for applications and plugins to use such as:

  • String getUserIdentity()
  • def getUserInfo()
  • boolean userHasRole(role)
  • boolean userIsAllowed(object, action)
  • def ifUserHasRole(role, Closure code)

You simply auto wire this bean into your classes using the name "grailsSecurity"

For more details see grailsSecurity.

4.1 Implementing a Security Bridge

To use the Security API, an application must have a Security Bridge bean that implements the SecurityBridge interface,

Typically this bean will be provided by the security plugin you are using. However you can easily implement your own in your own plugin or application.

Simply implement the interface and register the bean as "grailsSecurityBridge" in your Spring context either in a plugin's doWithSpring or your application's resources.groovy:

grailsSecurityBridge(com.mycorp.security.MySecurityProvider) {
    // wire in any other dependencies it has
    grailsApplication = ref('grailsApplication')

The interface is defined here:

interface SecurityBridge {
     * Implementations must return the name of their security provider 
     * @return A name such as "Spring Security"
    String getProviderName() 

     * Get user id string i.e. "marcpalmer" of the currently logged in user, from whatever
     * underlying security API is in force
     * @return the user name / identity String or null if nobody is logged in
    String getUserIdentity()

     * Get user info object containing i.e. email address, other stuff defined by the security implementation
     * @return the implementation's user object or null if nobody is logged in
    def getUserInfo()

     * Return true if the current logged in user has the specified role
    boolean userHasRole(role)

     * Can the current user access this object to perform the named action?
     * @param object The object, typically domain but we don't care what
     * @param action Some application-defined action string i.e. "view" or "edit"
    boolean userIsAllowed(object, action)
     * Create a link to the specified security action
     * @param action One of "login", "logout", "signup"
     * @return Must return a Map of arguments to pass to g:link to create the link
    Map createLink(String action)
     * Execute code masquerading as the specified user, for the duration of the Closure block
     * @return Whatever the closure returns
    def withUser(identity, Closure code)