1 Introduction to the Spring Security Plugin

This guide documents configuration defaults and describes how to configure and extend the Spring Security plugin for Grails applications.

Release History and Acknowledgment

• December 7, 2015
• 2.0.0 release
• November 16, 2015
• 2.0-RC6 release
• June 4, 2015
• 2.0-RC5 release
• July 8, 2014
• 2.0-RC4 release
• May 19, 2014
• 2.0-RC3 release
• October 4, 2013
• 2.0-RC2 release
• JIRA Issues
• October 3, 2013
• 2.0-RC1 release
• April 6, 2012
• 1.2.7.3 release
• JIRA Issues
• February 2, 2012
• 1.2.7.2 release
• JIRA Issues
• January 18, 2012
• 1.2.7.1 release
• JIRA Issues
• December 30, 2011
• 1.2.7 release
• JIRA Issues
• December 2, 2011
• 1.2.6 release
• JIRA Issues
• December 1, 2011
• 1.2.5 release
• October 18, 2011
• 1.2.4 release
• October 15, 2011
• 1.2.3 release
• October 15, 2011
• 1.2.2 release
• JIRA Issues
• August 17, 2011
• 1.2.1 release
• JIRA Issues
• July 31, 2011
• 1.2 release
• JIRA Issues
• May 23, 2011
• 1.1.3 release
• JIRA Issues
• February 26, 2011
• 1.1.2 release
• February 26, 2011
• 1.1.1 release
• JIRA Issues
• August 8, 2010
• 1.1 release
• JIRA Issues
• August 1, 2010
• 1.0.1 release
• July 27, 2010
• 1.0 release
• JIRA Issues
• July 16, 2010
• 0.4.2 release
• JIRA Issues
• June 29, 2010
• 0.4.1 release
• JIRA Issues
• June 21, 2010
• 0.4 release
• JIRA Issues
• May 12, 2010
• 0.3.1 release
• JIRA Issues
• May 12, 2010
• 0.3 release
• JIRA Issues
• May 2, 2010
• 0.2 release
• April 27, 2010
• initial 0.1 release

This plugin is based on work done for the Acegi plugin by Tsuyoshi Yamamoto.

1.1 Configuration Settings Now in Config.groovy

This structure enables environment-specific configuration such as, for example, fewer structure-restrictive security rules during development than in production. Like any environment-specific configuration parameters, you wrap them in an environments block.

The plugin's configuration values all start with grails.plugin.springsecurity to distinguish them from similarly named options in Grails and from other plugins. You must specify all property overrides with the grails.plugin.springsecurity suffix. For example, you specify the attribute password.algorithm as:

grails.plugin.springsecurity.password.algorithm='bcrypt'

in Config.groovy

1.2 Getting Started

To get started using the Spring Security plugin with your Grails application, see Tutorials.

You do not need to know much about Spring Security to use the plugin, but it can be helpful to understand the underlying implementation. See the Spring Security documentation.

2 What's New in Version 2.0

Package changes

All classes are now in the grails.plugin.springsecurity package or a subpackage. The names tend to correspond to the analagous Spring Security classes where appropriate, for example MutableLogoutFilter is in the grails.plugin.springsecurity.web.authentication.logout package to correspond with the org.springframework.security.web.authentication.logout package.

Some of the changes were more subtle though; for example all classes in the old grails.plugins.springsecurity packages and subpackages are now in grails.plugin.springsecurity, only one character different. This will result in a non-trivial upgrade process for your applications, but that is a benefit as it will hopefully point you at other important changes you might have otherwise missed.

Configuration prefix changes

The prefix used in Config.groovy for the plugin's configuration settings has changed from grails.plugins.springsecurity to grails.plugin.springsecurity.

More aggressively secure by default

In 1.x it was assumed that defaulting pages to not be secured, and configuring guarded URLs as needed, was a more pragmatic approach. Now however, all URLs are initially blocked unless there is a request mapping rule, even if that rule allows all access. The assumption behind this change is that if you forget to guard a new URL, it can take a long time to discover that users had access, whereas if you forget to open access for allowed users when using the "pessimistic" approach, nobody can access the URL and the error will be quickly discovered. This approach is more work, but much safer.

This is described in more detail here.

Logout POST only

By default only POST requests are allowed to trigger a logout. To allow GET access, add this

grails.plugin.springsecurity.logout.postOnly = false

bcrypt by default

The default password hashing algorithm is now bcrypt since it is a very robust hashing approach. PBKDF2 is similar and is also supported. You can still use any message digest algorithm that is supported in your JDK; see this Java page for the available algorithms.

New applications should use bcrypt or PBKDF2, but if you didn't change the default settings in previous versions of the plugin and want to continue using the same algorithm, use these settings:

grails.plugin.springsecurity.password.algorithm = 'SHA-256'
grails.plugin.springsecurity.password.hash.iterations = 1

Session Fixation Prevention by default

Session Fixation Prevention is now enabled by default, but can be disabled with

grails.plugin.springsecurity.useSessionFixationPrevention = false

@Secured annotation

As of Grails 2.0, controller actions can be defined as closures or methods, with methods being preferred. The @Secured annotation no longer supports being defined on controller action closures, so you will need to convert them to real methods.

You can also specify the HTTP method that an annotation is defined for (e.g. when using REST). When doing this you must explicitly name the value attribute, e.g.

@Secured(value=["hasRole('ROLE_ADMIN')"], httpMethod='POST')
def someMethod() {
   …
}

In addition, you can define a closure in the annotation which will be called during access checking. The closure must return true or false and has all of the methods and properties that are available when using SpEL expressions, since the closure's delegate is set to a subclass of WebSecurityExpressionRoot, and also the Spring ApplicationContext as the ctx property:

@Secured(closure = {
   assert request
   assert ctx
   authentication.name == 'admin1'
})
def someMethod() {
   …
}

Anonymous authentication

In standard Spring Security and older versions of the plugin, there is support for an "anonymous" authentication. This is implemented by a filter that registers a simple Authentication in the SecurityContext to remove the need for null checks, since there will always be an Authentication available. This approach is still problematic though because the Principal of the anonymous authentication is a String, whereas it is a UserDetails instance when there is a non-anonymous authentication.

Since you still have to be careful to differentiate between anonymous and non-anonymous authentications, the plugin now creates an anonymous Authentication which will be an instance of grails.plugin.springsecurity.authentication. GrailsAnonymousAuthenticationToken with a standard org.springframework.security.core.userdetails.User instance as its Principal. The authentication will have a single granted role, ROLE_ANONYMOUS.

No HQL

Some parts of the code used HQL queries, for example in the generated UserRole class and in SpringSecurityService.findRequestmapsByRole. These have been replaced by "where" queries to make data access more portable across GORM implementatioins.

Changes in generated classes

The enabled property in the generated User class now defaults to true. This will make creating instances a bit more DRY:

def u = new User(username: 'me', password: 'itsasecret').save()

If you prefer the old approach, change your generated class.

Also, the plugin includes the grails.plugin.springsecurity.LoginController.groovy and grails.plugin.springsecurity.LogoutController.groovy controllers, and grails-app/views/auth.gsp and grails-app/views/denied.gsp GSPs. If you had no need previously to change these you can delete your files and the plugins' files will be used instead. If you do want to change them, copy each as needed to your application and make the required changes, and yours will be used instead.

One small change is that there is no longer a default value for the domain class name properties (userLookup.userDomainClassName, authority.className, requestMap.className, rememberMe.persistentToken.domainClassName). This was of little use and tended to cause confusing error messages when there was a misconfiguration.

SecurityContextHolder strategy

You can now define the SecurityContextHolder strategy. By default it is stored in a ThreadLocal, but you can also configure it to use an InheritableThreadLocal to maintain the context in new threads, or a custom class that implements the org.springframework.security.core.context.SecurityContextHolderStrategy interface. To change the strategy, set the grails.plugin.springsecurity.sch.strategyName config property to "MODE_THREADLOCAL" (the default) to use a ThreadLocal, "MODE_INHERITABLETHREADLOCAL" to use an InheritableThreadLocal, or the name of a class that implements SecurityContextHolderStrategy.

Debug filter

You can enable a "debug" filter based on the org.springframework.security.config.debug.DebugFilter class. It will log security information at the "info" level and can help when debugging configuration issues. This should only be enabled in development mode so consider adding the property that enables it inside an environments block in Config.groovy

environments {
   development {
      grails.logging.jul.usebridge = true
      grails.plugin.springsecurity.debug.useFilter = true
   }
   production {
      grails.logging.jul.usebridge = false
   }
}

Also add the implementation class name in your Log4j configuration:

info 'grails.plugin.springsecurity.web.filter.DebugFilter'

Storing usernames in the session

In Spring Security 3.0 and earlier, the username was stored in the HTTP session under the key "SPRING_SECURITY_LAST_USERNAME". This no longer done, but the plugin will use the old behavior if the grails.plugin.springsecurity.apf.storeLastUsername setting is set to true (the default is false ). Further, the name is no longer escaped before storing, it is stored exactly as entered by the user, so you must escape it when redisplaying to avoid XSS attacks.

@Authorities annotation

You can use the new @Authorities annotation to make your annotations more DRY. See this blog post for a description about the motivation and implementation details. Note that the package for the annotation in the plugin is grails.plugin.springsecurity.annotation, not grails.plugins.springsecurity.annotation as described in the blog post.

Miscellaneous changes

AuthenticationDetailsSource

Previously you could configure the details class that was constructed by the authenticationDetailsSource bean by setting the authenticationDetails.authClass property. In Spring Security 3.2 this isn't possible because WebAuthenticationDetailsSource always returns a WebAuthenticationDetails. But you can still customize the details class by creating a class that implements the AuthenticationDetailsSource interface, e.g.:

package com.mycompany;
import javax.servlet.http.HttpServletRequest;
import org.springframework.security.authentication.AuthenticationDetailsSource;
public class MyAuthenticationDetailsSource implements AuthenticationDetailsSource<HttpServletRequest, MyWebAuthenticationDetails> {
   public MyWebAuthenticationDetails buildDetails(HttpServletRequest context) {
      // build a MyWebAuthenticationDetails
   }
}

and registering that as the authenticationDetailsSource bean in resources.groovy

import com.mycompany.MyAuthenticationDetailsSource
beans = {
   authenticationDetailsSource(MyAuthenticationDetailsSource) {
      // any required properties
   }
}

3 Domain Classes

To use the standard user lookup you'll need at a minimum a 'person' and an 'authority' domain class. In addition, if you want to store URL<->Role mappings in the database (this is one of multiple approaches for defining the mappings) you need a 'requestmap' domain class. If you use the recommended approach for mapping the many-to-many relationship between 'person' and 'authority,' you also need a domain class to map the join table.

To use the user/group lookup you'll also need a 'group' domain class. If you are using the recommended approach for mapping many-to-many relationship between 'person' and 'group' and between 'group' and 'authority' you'll need a domain class for each to map the join tables. You can still additionally use 'requestmap' with this approach.

The s2-quickstart script creates initial domain classes for you. You specify the package and class names, and it creates the corresponding domain classes. After that you can customize them as you like. You can add unlimited fields, methods, and so on, as long as the core security-related functionality remains.

3.1 Person Class

By default the plugin uses a Grails 'person' domain class to manage this data. username, enabled, password are the default names of the core required properties. You can easily plug in your own implementation, and rename the class, package, and fields. In addition, you should define an authorities property to retrieve roles; this can be a public field or a getAuthorities() method, and it can be defined through a traditional GORM many-to-many or a custom mapping.

Assuming you choose com.mycompany.myapp as your package, and User as your class name, you'll generate this class:

package com.mycompany.myapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='username')
@ToString(includes='username', includeNames=true, includePackage=false)
class User implements Serializable {
   private static final long serialVersionUID = 1
   transient springSecurityService
   String username
   String password
   boolean enabled = true
   boolean accountExpired
   boolean accountLocked
   boolean passwordExpired
   User(String username, String password) {
      this()
      this.username = username
      this.password = password
   }
   Set<Role> getAuthorities() {
      UserRole.findAllByUser(this)*.role
   }
   def beforeInsert() {
      encodePassword()
   }
   def beforeUpdate() {
      if (isDirty('password')) {
         encodePassword()
      }
   }
   protected void encodePassword() {
      password = springSecurityService?.passwordEncoder ?
         springSecurityService.encodePassword(password) :
         password
   }
   static transients = ['springSecurityService']
   static constraints = {
      username blank: false, unique: true
      password blank: false
   }
   static mapping = {
      password column: '`password`'
   }
}

Optionally, add other properties such as email, firstName, lastName, and convenience methods, and so on:

package com.mycompany.myapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='username')
@ToString(includes='username', includeNames=true, includePackage=false)
class User implements Serializable {
   private static final long serialVersionUID = 1
   transient springSecurityService
   String username
   String password
   boolean enabled = true
   String email
   String firstName
   String lastName
   boolean accountExpired
   boolean accountLocked
   boolean passwordExpired
   User(String username, String password) {
      this()
      this.username = username
      this.password = password
   }
   def someMethod {
      …
   }
   Set<Role> getAuthorities() {
      UserRole.findAllByUser(this)*.role
   }
   def beforeInsert() {
      encodePassword()
   }
   def beforeUpdate() {
      if (isDirty('password')) {
         encodePassword()
      }
   }
   protected void encodePassword() {
      password = springSecurityService?.passwordEncoder ?
         springSecurityService.encodePassword(password) :
         password
   }
   static transients = ['springSecurityService']
   static constraints = {
      username blank: false, unique: true
      password blank: false
   }
   static mapping = {
      password column: '`password`'
   }
}

The getAuthorities() method is analagous to defining static hasMany = [authorities: Authority] in a traditional many-to-many mapping. This way GormUserDetailsService can call user.authorities during login to retrieve the roles without the overhead of a bidirectional many-to-many mapping.

The class and property names are configurable using these configuration attributes:

3.2 Authority Class

Like the 'person' class, the 'authority' class has a default name, Authority, and a default name for its one required property, authority. If you want to use another existing domain class, it simply has to have a property for name. As with the name of the class, the names of the properties can be whatever you want - they're specified in grails-app/conf/Config.groovy.

Assuming you choose com.mycompany.myapp as your package, and Role as your class name, you'll generate this class:

package com.mycompany.myapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='authority')
@ToString(includes='authority', includeNames=true, includePackage=false)
class Role implements Serializable {
   private static final long serialVersionUID = 1
   String authority
   Role(String authority) {
      this()
      this.authority = authority
   }
   static constraints = {
      authority blank: false, unique: true
   }
   static mapping = {
      cache true
   }
}

The class and property names are configurable using these configuration attributes:

Role names must start with "ROLE_". This is configurable in Spring Security, but not in the plugin. It would be possible to allow different prefixes, but it's important that the prefix not be blank as the prefix is used to differentiate between role names and tokens such as IS_AUTHENTICATED_FULLY, IS_AUTHENTICATED_ANONYMOUSLY, etc., and SpEL expressions.

The role names should be primarily an internal implementation detail; if you want to display friendlier names in a UI, it's simple to remove the prefix first.

3.3 PersonAuthority Class

Like the other domain classes, this class is generated for you, so you don't need to deal with the details of mapping it. Assuming you choose com.mycompany.myapp as your package, and User and Role as your class names, you'll generate this class:

package com.mycompany.myapp
import grails.gorm.DetachedCriteria
import groovy.transform.ToString
import org.apache.commons.lang.builder.HashCodeBuilder
@ToString(cache=true, includeNames=true, includePackage=false)
class UserRole implements Serializable {
   private static final long serialVersionUID = 1
   User user
   Role role
   UserRole(User u, Role r) {
      this()
      user = u
      role = r
   }
   @Override
   boolean equals(other) {
      if (!(other instanceof UserRole)) {
         return false
      }
      other.user?.id == user?.id &&
      other.role?.id == role?.id
   }
   @Override
   int hashCode() {
      def builder = new HashCodeBuilder()
      if (user) builder.append(user.id)
      if (role) builder.append(role.id)
      builder.toHashCode()
   }
   static UserRole get(long userId, long roleId) {
      criteriaFor(userId, roleId).get()
   }
   static boolean exists(long userId, long roleId) {
      criteriaFor(userId, roleId).count()
   }
   private static DetachedCriteria criteriaFor(long userId, long roleId) {
      UserRole.where {
         user == User.load(userId) &&
         role == Role.load(roleId)
      }
   }
   static UserRole create(User user, Role role, boolean flush = false) {
      def instance = new UserRole(user: user, role: role)
      instance.save(flush: flush, insert: true)
      instance
   }
   static boolean remove(User u, Role r, boolean flush = false) {
      if (u == null || r == null) return false
      int rowCount = UserRole.where { user == u && role == r }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
      rowCount
   }
   static void removeAll(User u, boolean flush = false) {
      if (u == null) return
      UserRole.where { user == u }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
   }
   static void removeAll(Role r, boolean flush = false) {
      if (r == null) return
      UserRole.where { role == r }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
   }
   static constraints = {
      role validator: { Role r, UserRole ur ->
         if (ur.user == null || ur.user.id == null) return
         boolean existing = false
         UserRole.withNewSession {
            existing = UserRole.exists(ur.user.id, r.id)
         }
         if (existing) {
            return 'userRole.exists'
         }
      }
   }
   static mapping = {
      id composite: ['user', 'role']
      version false
   }
}

The helper methods make it easy to grant or revoke roles. Assuming you have already loaded a user and a role, you grant the role to the user as follows:

User user = …
Role role = …
UserRole.create user, role

Or by using the 3-parameter version to trigger a flush:

User user = …
Role role = …
UserRole.create user, role, true

Revoking a role is similar:

User user = …
Role role = …
UserRole.remove user, role

Or:

User user = …
Role role = …
UserRole.remove user, role, true

The class name is the only configurable attribute:

3.4 Group Class

If you run the s2-quickstart script with the group name specified and use com.mycompany.myapp as your package and RoleGroup and Role as your class names, you'll generate this class:

package com.mycompany.myapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='name')
@ToString(includes='name', includeNames=true, includePackage=false)
class RoleGroup implements Serializable {
   private static final long serialVersionUID = 1
   String name
   RoleGroup(String name) {
      this()
      this.name = name
   }
   Set<Role> getAuthorities() {
      RoleGroupRole.findAllByRoleGroup(this)*.role
   }
   static constraints = {
      name blank: false, unique: true
   }
   static mapping = {
      cache true
   }
}

When running the s2-quickstart script with the group name specified, the 'person' class will be generated differently to accommodate the use of groups. Assuming you use com.mycompany.myapp as your package and User and RoleGroup as your class names, the getAuthorities() method will be generated like so:

Set<RoleGroup> getAuthorities() {
   UserRoleGroup.findAllByUser(this).collect { it.roleGroup }
}

The plugin assumes the attribute authorities will provide the 'authority' collection for each class, but you can change the field names in grails-app/conf/Config.groovy. You also must ensure that the property useRoleGroups is set to true in order for GormUserDetailsService to properly attain the authorities.

3.5 PersonGroup Class

If you run the s2-quickstart script with the group name specified, this class will be generated for you, so you don't need to deal with the details of mapping it. Assuming you choose com.mycompany.myapp as your package, and User and RoleGroup as your class names, you'll generate this class:

package com.mycompany.myapp
import grails.gorm.DetachedCriteria
import groovy.transform.ToString
import org.apache.commons.lang.builder.HashCodeBuilder
@ToString(cache=true, includeNames=true, includePackage=false)
class UserRoleGroup implements Serializable {
   private static final long serialVersionUID = 1
   User user
   RoleGroup roleGroup
   UserRoleGroup(User u, RoleGroup rg) {
      this()
      user = u
      roleGroup = rg
   }
   @Override
   boolean equals(other) {
      if (!(other instanceof UserRoleGroup)) {
         return false
      }
      other.user?.id == user?.id &&
      other.roleGroup?.id == roleGroup?.id
   }
   @Override
   int hashCode() {
      def builder = new HashCodeBuilder()
      if (user) builder.append(user.id)
      if (roleGroup) builder.append(roleGroup.id)
      builder.toHashCode()
   }
   static UserRoleGroup get(long userId, long roleGroupId) {
      criteriaFor(userId, roleGroupId).get()
   }
   static boolean exists(long userId, long roleGroupId) {
      criteriaFor(userId, roleGroupId).count()
   }
   private static DetachedCriteria criteriaFor(long userId, long roleGroupId) {
      UserRoleGroup.where {
         user == User.load(userId) &&
         roleGroup == RoleGroup.load(roleGroupId)
      }
   }
   static UserRoleGroup create(User user, RoleGroup roleGroup,
                               boolean flush = false) {
      def instance = new UserRoleGroup(user: user, roleGroup: roleGroup)
      instance.save(flush: flush, insert: true)
      instance
   }
   static boolean remove(User u, RoleGroup rg, boolean flush = false) {
      if (u == null || rg == null) return false
      int rowCount = UserRoleGroup.where { user == u && roleGroup == rg }.deleteAll()
      if (flush) { UserRoleGroup.withSession { it.flush() } }
      rowCount
   }
   static void removeAll(User u, boolean flush = false) {
      if (u == null) return
      UserRoleGroup.where { user == u }.deleteAll()
      if (flush) { UserRoleGroup.withSession { it.flush() } }
   }
   static void removeAll(RoleGroup rg, boolean flush = false) {
      if (rg == null) return
      UserRoleGroup.where { roleGroup == rg }.deleteAll()
      if (flush) { UserRoleGroup.withSession { it.flush() } }
   }
   static constraints = {
      user validator: { User u, UserRoleGroup ug ->
         if (ug.roleGroup == null || ug.roleGroup.id == null) return
         boolean existing = false
         UserRoleGroup.withNewSession {
            existing = UserRoleGroup.exists(u.id, ug.roleGroup.id)
         }
         if (existing) {
            return 'userGroup.exists'
         }
      }
   }
   static mapping = {
      id composite: ['roleGroup', 'user']
      version false
   }
}

3.6 GroupAuthority Class

If you run the s2-quickstart script with the group name specified, this class will be generated for you, so you don't need to deal with the details of mapping it. Assuming you choose com.mycompany.myapp as your package, and RoleGroup and Role as your class names, you'll generate this class:

package com.mycompany.myapp
import grails.gorm.DetachedCriteria
import groovy.transform.ToString
import org.apache.commons.lang.builder.HashCodeBuilder
@ToString(cache=true, includeNames=true, includePackage=false)
class RoleGroupRole implements Serializable {
   private static final long serialVersionUID = 1
   RoleGroup roleGroup
   Role role
   RoleGroupRole(RoleGroup g, Role r) {
      this()
      roleGroup = g
      role = r
   }
   @Override
   boolean equals(other) {
      if (!(other instanceof RoleGroupRole)) {
         return false
      }
      other.role?.id == role?.id &&
      other.roleGroup?.id == roleGroup?.id
   }
   @Override
   int hashCode() {
      def builder = new HashCodeBuilder()
      if (roleGroup) builder.append(roleGroup.id)
      if (role) builder.append(role.id)
      builder.toHashCode()
   }
   static RoleGroupRole get(long roleGroupId, long roleId) {
      criteriaFor(roleGroupId, roleId).get()
   }
   static boolean exists(long roleGroupId, long roleId) {
      criteriaFor(roleGroupId, roleId).count()
   }
   private static DetachedCriteria criteriaFor(long roleGroupId, long roleId) {
      RoleGroupRole.where {
         roleGroup == RoleGroup.load(roleGroupId) &&
         role == Role.load(roleId)
      }
   }
   static RoleGroupRole create(RoleGroup roleGroup, Role role,
                               boolean flush = false) {
      def instance = new RoleGroupRole(roleGroup: roleGroup, role: role)
      instance.save(flush: flush, insert: true)
      instance
   }
   static boolean remove(RoleGroup rg, Role r, boolean flush = false) {
      if (rg == null || r == null) return false
      int rowCount = RoleGroupRole.where { roleGroup == rg && role == r }.deleteAll()
      if (flush) { RoleGroupRole.withSession { it.flush() } }
      rowCount
   }
   static void removeAll(Role r, boolean flush = false) {
      if (r == null) return
      RoleGroupRole.where { role == r }.deleteAll()
      if (flush) { RoleGroupRole.withSession { it.flush() } }
   }
   static void removeAll(RoleGroup rg, boolean flush = false) {
      if (rg == null) return
      RoleGroupRole.where { roleGroup == rg }.deleteAll()
      if (flush) { RoleGroupRole.withSession { it.flush() } }
   }
   static constraints = {
      role validator: { Role r, RoleGroupRole rg ->
         if (rg.roleGroup == null || rg.roleGroup.id == null) return
         boolean existing = false
         RoleGroupRole.withNewSession {
            existing = RoleGroupRole.exists(rg.roleGroup.id, r.id)
         }
         if (existing) {
            return 'roleGroup.exists'
         }
      }
   }
   static mapping = {
      id composite: ['roleGroup', 'role']
      version false
   }
}

3.7 Requestmap Class

Assuming you choose com.mycompany.myapp as your package, and Requestmap as your class name, you'll generate this class:

package com.mycompany.myapp
import org.springframework.http.HttpMethod
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes=['configAttribute', 'httpMethod', 'url'])
@ToString(includes=['configAttribute', 'httpMethod', 'url'], cache=true, includeNames=true, includePackage=false)
class Requestmap implements Serializable {
   private static final long serialVersionUID = 1
   String configAttribute
   HttpMethod httpMethod
   String url
   Requestmap(String url, String configAttribute,
              HttpMethod httpMethod = null) {
      this()
      this.configAttribute = configAttribute
      this.httpMethod = httpMethod
      this.url = url
   }
   static constraints = {
      configAttribute blank: false
      httpMethod nullable: true
      url blank: false, unique: 'httpMethod'
   }
   static mapping = {
      cache true
   }
}

To use Requestmap entries to guard URLs, see Requestmap Instances Stored in the Database.

4 Configuring Request Mappings to Secure URLs

• @Secured annotations (default approach)
• A simple Map in Config.groovy
• Requestmap domain class instances stored in the database

You can only use one method at a time. You configure it with the securityConfigType attribute; the value has to be an SecurityConfigType enum value or the name of the enum as a String.

Pessimistic Lockdown

Many applications are mostly public, with some pages only accessible to authenticated users with various roles. In this case, it might make sense to leave URLs open by default and restrict access on a case-by-case basis. However, if your application is primarily secure, you can use a pessimistic lockdown approach to deny access to all URLs that do not have an applicable URL-Role request mapping. But the pessimistic approach is safer; if you forget to restrict access to a URL using the optimistic approach, it might take a while to discover that unauthorized users can access the URL, but if you forget to allow access when using the pessimistic approach, no user can access it and the error should be quickly discovered.

The pessimistic approach is the default, and there are two configuration options that apply. If rejectIfNoRule is true (the default) then any URL that has no request mappings (an annotation, entry in controllerAnnotations.staticRules or interceptUrlMap, or a Requestmap instance) will be denied to all users. The other option is fii.rejectPublicInvocations and if it is true (the default) then un-mapped URLs will trigger an IllegalArgumentException and will show the error page. This is uglier, but more useful because it's very clear that there is a misconfiguration. When fii.rejectPublicInvocations is false but rejectIfNoRule is true you just see the "Sorry, you're not authorized to view this page." error 403 message.

Note that the two settings are mutually exclusive. If rejectIfNoRule is true then fii.rejectPublicInvocations is ignored because the request will transition to the login page or the error 403 page. If you want the more obvious error page, set fii.rejectPublicInvocations to true and rejectIfNoRule to false to allow that check to occur.

To reject un-mapped URLs with a 403 error code, use these settings (or none since rejectIfNoRule defaults to true )

grails.plugin.springsecurity.rejectIfNoRule = true
grails.plugin.springsecurity.fii.rejectPublicInvocations = false

and to reject with the error 500 page, use these (optionally omit rejectPublicInvocations since it defaults to true ):

grails.plugin.springsecurity.rejectIfNoRule = false
grails.plugin.springsecurity.fii.rejectPublicInvocations = true

Note that if you set rejectIfNoRule or rejectPublicInvocations to true you'll need to configure the staticRules map to include URLs that can't otherwise be guarded:

grails.plugin.springsecurity.controllerAnnotations.staticRules = [
   '/':               ['permitAll'],
   '/index':          ['permitAll'],
   '/index.gsp':      ['permitAll'],
   '/assets/**':      ['permitAll'],
   '/**/js/**':       ['permitAll'],
   '/**/css/**':      ['permitAll'],
   '/**/images/**':   ['permitAll'],
   '/**/favicon.ico': ['permitAll']
]

This is needed when using annotations; if you use the grails.plugin.springsecurity.interceptUrlMap map in Config.groovy you'll need to add these URLs too, and likewise when using Requestmap instances. If you don't use annotations, you must add rules for the login and logout controllers also. You can add Requestmaps manually, or in BootStrap.groovy, for example:

for (String url in [
      '/', '/index', '/index.gsp', '/**/favicon.ico',
      '/**/js/**', '/**/css/**', '/**/images/**',
      '/login', '/login.*', '/login/*',
      '/logout', '/logout.*', '/logout/*']) {
   new Requestmap(url: url, configAttribute: 'permitAll').save()
}

The analogous interceptUrlMap settings would be:

grails.plugin.springsecurity.interceptUrlMap = [
   '/':                ['permitAll'],
   '/index':           ['permitAll'],
   '/index.gsp':       ['permitAll'],
   '/assets/**':       ['permitAll'],
   '/**/js/**':        ['permitAll'],
   '/**/css/**':       ['permitAll'],
   '/**/images/**':    ['permitAll'],
   '/**/favicon.ico':  ['permitAll'],
   '/login/**':        ['permitAll'],
   '/logout/**':       ['permitAll']
]

In addition, when you enable the switch-user feature, you'll have to specify access rules for the associated URLs, e.g.

'/j_spring_security_switch_user': ['ROLE_ADMIN'],
'/j_spring_security_exit_user':   ['permitAll']

URLs and Authorities

In each approach you configure a mapping for a URL pattern to the role(s) that are required to access those URLs, for example, /admin/user/** requires ROLE_ADMIN. In addition, you can combine the role(s) with tokens such as IS_AUTHENTICATED_ANONYMOUSLY, IS_AUTHENTICATED_REMEMBERED, and IS_AUTHENTICATED_FULLY. One or more Voters will process any tokens and enforce a rule based on them:

• IS_AUTHENTICATED_ANONYMOUSLY
• signifies that anyone can access this URL. By default the AnonymousAuthenticationFilter ensures an 'anonymous' Authentication with no roles so that every user has an authentication. The token accepts any authentication, even anonymous.
• IS_AUTHENTICATED_REMEMBERED
• requires the user to be authenticated through a remember-me cookie or an explicit login.
• IS_AUTHENTICATED_FULLY
• requires the user to be fully authenticated with an explicit login.

With IS_AUTHENTICATED_FULLY you can implement a security scheme whereby users can check a remember-me checkbox during login and be auto-authenticated each time they return to your site, but must still log in with a password for some parts of the site. For example, allow regular browsing and adding items to a shopping cart with only a cookie, but require an explicit login to check out or view purchase history.

For more information on IS_AUTHENTICATED_FULLY, IS_AUTHENTICATED_REMEMBERED, and IS_AUTHENTICATED_ANONYMOUSLY, see the Javadoc for AuthenticatedVoter

The plugin isn't compatible with Grails <g:actionSubmit> tags. These are used in the autogenerated GSPs that are created for you, and they enable having multiple submit buttons, each with its own action, inside a single form. The problem from the security perspective is that the form posts to the default action of the controller, and Grails figures out the handler action to use based on the action attribute of the actionSubmit tag. So for example you can guard the /person/delete with a restrictive role, but given this typical edit form:

<g:form>
   …
   <g:actionSubmit class="save" action="update"
                   value='Update' />
   <g:actionSubmit class="delete" action="delete"
                   value="'Delete' />
</g:form>

both actions will be allowed if the user has permission to access the /person/index url, which would often be the case.

The workaround is to create separate forms without using actionSubmit and explicitly set the action on the <g:form> tags, which will result in form submissions to the expected urls and properly guarded urls.

Comparing the Approaches

Each approach has its advantages and disadvantages. Annotations and the Config.groovy Map are less flexible because they are configured once in the code and you can update them only by restarting the application (in prod mode anyway). In practice this limitation is minor, because security mappings for most applications are unlikely to change at runtime.

On the other hand, storing Requestmap entries enables runtime-configurability. This approach gives you a core set of rules populated at application startup that you can edit, add to, and delete as needed. However, it separates the security rules from the application code, which is less convenient than having the rules defined in grails-app/conf/Config.groovy or in the applicable controllers using annotations.

URLs must be mapped in lowercase if you use the Requestmap or grails-app/conf/Config.groovy map approaches. For example, if you have a FooBarController, its urls will be of the form /fooBar/list, /fooBar/create, and so on, but these must be mapped as /foobar/, /foobar/list, /foobar/create. This mapping is handled automatically for you if you use annotations.

4.1 Defining Secured Annotations

grails.plugin.springsecurity.securityConfigType = "Annotation"

You can define the annotation at the class level, meaning that the specified roles are required for all actions, or at the action level, or both. If the class and an action are annotated then the action annotation values will be used since they're more specific.

For example, given this controller:

package com.mycompany.myapp
import grails.plugin.springsecurity.annotation.Secured
class SecureAnnotatedController {
   @Secured(['ROLE_ADMIN'])
   def index() {
      render 'you have ROLE_ADMIN'
   }
   @Secured(['ROLE_ADMIN', 'ROLE_SUPERUSER'])
   def adminEither() {
      render 'you have ROLE_ADMIN or SUPERUSER'
   }
   def anybody() {
      render 'anyone can see this' // assuming you're not using "strict" mode, otherwise the action is not viewable by anyone
   }
}

you must be authenticated and have ROLE_ADMIN to see /myapp/secureAnnotated (or /myapp/secureAnnotated/index) and be authenticated and have ROLE_ADMIN or ROLE_SUPERUSER to see /myapp/secureAnnotated/adminEither. Any user can access /myapp/secureAnnotated/anybody if you have disabled "strict" mode (using rejectIfNoRule), and nobody can access the action by default since it has no access rule configured.

In addition, you can define a closure in the annotation which will be called during access checking. The closure must return true or false and has all of the methods and properties that are available when using SpEL expressions, since the closure's delegate is set to a subclass of WebSecurityExpressionRoot, and also the Spring ApplicationContext as the ctx property:

@Secured(closure = {
   assert request
   assert ctx
   authentication.name == 'admin1'
})
def someMethod() {
   …
}

Often most actions in a controller require similar access rules, so you can also define annotations at the class level:

package com.mycompany.myapp
import grails.plugin.springsecurity.annotation.Secured
@Secured(['ROLE_ADMIN'])
class SecureClassAnnotatedController {
   def index() {
      render 'index: you have ROLE_ADMIN'
   }
   def otherAction() {
      render 'otherAction: you have ROLE_ADMIN'
   }
   @Secured(['ROLE_SUPERUSER'])
   def super() {
      render 'super: you have ROLE_SUPERUSER'
   }
}

Here you need to be authenticated and have ROLE_ADMIN to see /myapp/secureClassAnnotated (or /myapp/secureClassAnnotated/index) or /myapp/secureClassAnnotated/otherAction. However, you must have ROLE_SUPERUSER to access /myapp/secureClassAnnotated/super. The action-scope annotation overrides the class-scope annotation. Note that "strict" mode isn't applicable here since all actions have an access rule defined (either explicitly or inherited from the class-level annotation).

Securing RESTful domain classes

Since Grails 2.3, domain classes can be annotated with the grails.rest.Resource AST transformation, which will generate internally a controller with the default CRUD operations.

You can also use the @Secured annotation on such domain classes:

@Resource
@Secured('ROLE_ADMIN')
class Thing {
   String name
}

Additionally, you can specify the HTTP method that is required in each annotation for the access rule, e.g.

package com.mycompany.myapp
import grails.plugin.springsecurity.annotation.Secured
class SecureAnnotatedController {
   @Secured(value = ['ROLE_ADMIN'], httpMethod = 'GET')
   def create() {
      …
   }
   @Secured(value = ['ROLE_ADMIN'], httpMethod = 'POST')
   def save() {
      …
   }
}

Here you must have ROLE_ADMIN for both the create and save actions but create requires a GET request (since it renders the form to create a new instance) and save requires POST (since it's the action that the form posts to).

controllerAnnotations.staticRules

You can also define 'static' mappings that cannot be expressed in the controllers, such as '/**' or for JavaScript, CSS, or image URLs. Use the controllerAnnotations.staticRules property, for example:

grails.plugin.springsecurity.controllerAnnotations.staticRules = [
   …
   '/js/admin/**': ['ROLE_ADMIN'],
   '/someplugin/**': ['ROLE_ADMIN']
]

This example maps all URLs associated with SomePluginController, which has URLs of the form /somePlugin/..., to ROLE_ADMIN; annotations are not an option here because you would not edit plugin code for a change like this.

When mapping URLs for controllers that are mapped in UrlMappings.groovy, you need to secure the un-url-mapped URLs. For example if you have a FooBarController that you map to /foo/bar/$action, you must register that in controllerAnnotations.staticRules as /foobar/**. This is different than the mapping you would use for the other two approaches and is necessary because controllerAnnotations.staticRules entries are treated as if they were annotations on the corresponding controller.

4.2 Simple Map in Config.groovy

grails.plugin.springsecurity.securityConfigType = "InterceptUrlMap"

Define a Map in Config.groovy:

grails.plugin.springsecurity.interceptUrlMap = [
   '/':                ['permitAll'],
   '/index':           ['permitAll'],
   '/index.gsp':       ['permitAll'],
   '/assets/**':       ['permitAll'],
   '/**/js/**':        ['permitAll'],
   '/**/css/**':       ['permitAll'],
   '/**/images/**':    ['permitAll'],
   '/**/favicon.ico':  ['permitAll'],
   '/login/**':        ['permitAll'],
   '/logout/**':       ['permitAll'],
   '/secure/**':       ['ROLE_ADMIN'],
   '/finance/**':      ['ROLE_FINANCE', 'isFullyAuthenticated()'],
]

When using this approach, make sure that you order the rules correctly. The first applicable rule is used, so for example if you have a controller that has one set of rules but an action that has stricter access rules, e.g.

'/secure/**':              ['ROLE_ADMIN', 'ROLE_SUPERUSER'],
'/secure/reallysecure/**': ['ROLE_SUPERUSER']

then this would fail - it wouldn't restrict access to /secure/reallysecure/list to a user with ROLE_SUPERUSER since the first URL pattern matches, so the second would be ignored. The correct mapping would be

'/secure/reallysecure/**': ['ROLE_SUPERUSER']
'/secure/**':              ['ROLE_ADMIN', 'ROLE_SUPERUSER'],

4.3 Requestmap Instances Stored in the Database

To use Requestmap entries, specify securityConfigType="Requestmap":

grails.plugin.springsecurity.securityConfigType = "Requestmap"

You create Requestmap entries as you create entries in any Grails domain class:

for (String url in [
      '/', '/index', '/index.gsp', '/**/favicon.ico',
      '/assets/**', '/**/js/**', '/**/css/**', '/**/images/**',
      '/login', '/login.*', '/login/*',
      '/logout', '/logout.*', '/logout/*']) {
   new Requestmap(url: url, configAttribute: 'permitAll').save()
}
new Requestmap(url: '/profile/**',    configAttribute: 'ROLE_USER').save()
new Requestmap(url: '/admin/**',      configAttribute: 'ROLE_ADMIN').save()
new Requestmap(url: '/admin/role/**', configAttribute: 'ROLE_SUPERVISOR').save()
new Requestmap(url: '/admin/user/**', configAttribute: 'ROLE_ADMIN,ROLE_SUPERVISOR').save()
new Requestmap(url: '/j_spring_security_switch_user',
               configAttribute: 'ROLE_SWITCH_USER,isFullyAuthenticated()').save()

The configAttribute value can have a single value or have multiple comma-delimited values. In this example only users with ROLE_ADMIN or ROLE_SUPERVISOR can access /admin/user/** urls, and only users with ROLE_SWITCH_USER can access the switch-user url (/j_spring_security_switch_user) and in addition must be authenticated fully, i.e. not using a remember-me cookie. Note that when specifying multiple roles, the user must have at least one of them, but when combining IS_AUTHENTICATED_FULLY, IS_AUTHENTICATED_REMEMBERED, or IS_AUTHENTICATED_ANONYMOUSLY (or their corresponding SpEL expressions) with one or more roles means the user must have one of the roles and satisty the IS_AUTHENTICATED rule.

Unlike the Config.groovy Map approach, you do not need to revise the Requestmap entry order because the plugin calculates the most specific rule that applies to the current request.

Requestmap Cache

Requestmap entries are cached for performance, but caching affects runtime configurability. If you create, edit, or delete an instance, the cache must be flushed and repopulated to be consistent with the database. You can call springSecurityService.clearCachedRequestmaps() to do this. For example, if you create a RequestmapController the save action should look like this (and the update and delete actions should similarly call clearCachedRequestmaps()):

class RequestmapController {
   def springSecurityService
   ...
   def save() {
      def requestmapInstance = new Requestmap(params)
      if (!requestmapInstance.save(flush: true)) {
         render view: 'create', model: [requestmapInstance: requestmapInstance]
         return
      }
      springSecurityService.clearCachedRequestmaps()
      flash.message = "${message(code: 'default.created.message', args: [message(code: 'requestmap.label', default: 'Requestmap'), requestmapInstance.id])}"
      redirect action: 'show', id: requestmapInstance.id
   }
}

4.4 Using Expressions to Create Descriptive, Fine-Grained Rules

You can use expressions with any of the previously described approaches to securing application URLs. For example, consider this annotated controller:

package com.yourcompany.yourapp
import grails.plugin.springsecurity.annotation.Secured
class SecureController {
   @Secured(["hasRole('ROLE_ADMIN')"])
   def someAction() {
      …
   }
   @Secured(["authentication.name == 'ralph'"])
   def someOtherAction() {
      …
   }
}

In this example, someAction requires ROLE_ADMIN, and someOtherAction requires that the user be logged in with username 'ralph'.

The corresponding Requestmap URLs would be

new Requestmap(url: "/secure/someAction",
               configAttribute: "hasRole('ROLE_ADMIN')").save()
new Requestmap(url: "/secure/someOtherAction",
               configAttribute: "authentication.name == 'ralph'").save()

and the corresponding static mappings would be

grails.plugin.springsecurity.interceptUrlMap = [
   '/secure/someAction':      ["hasRole('ROLE_ADMIN')"],
   '/secure/someOtherAction': ["authentication.name == 'ralph'"]
]

The Spring Security docs have a table listing the standard expressions, which is copied here for reference:

In addition, you can use a web-specific expression hasIpAddress. However, you may find it more convenient to separate IP restrictions from role restrictions by using the IP address filter.

To help you migrate traditional configurations to expressions, this table compares various configurations and their corresponding expressions:

5 Helper Classes

5.1 SecurityTagLib

ifLoggedIn

Example:

<sec:ifLoggedIn>
Welcome Back!
</sec:ifLoggedIn>

ifNotLoggedIn

Example:

<sec:ifNotLoggedIn>
<g:link controller='login' action='auth'>Login</g:link>
</sec:ifNotLoggedIn>

ifAllGranted

Example:

<sec:ifAllGranted roles="ROLE_ADMIN,ROLE_SUPERVISOR">secure stuff here</sec:ifAllGranted>

ifAnyGranted

Example:

<sec:ifAnyGranted roles="ROLE_ADMIN,ROLE_SUPERVISOR">secure stuff here</sec:ifAnyGranted>

ifNotGranted

Example:

<sec:ifNotGranted roles="ROLE_USER">non-user stuff here</sec:ifNotGranted>

loggedInUserInfo

<sec:loggedInUserInfo field="username"/>

If you have customized the UserDetails (e.g. with a custom UserDetailsService) to add a fullName property, you access it as follows:

Welcome Back <sec:loggedInUserInfo field="fullName"/>

username

<sec:ifLoggedIn>
Welcome Back <sec:username/>!
</sec:ifLoggedIn>
<sec:ifNotLoggedIn>
<g:link controller='login' action='auth'>Login</g:link>
</sec:ifNotLoggedIn>

ifSwitched

<sec:ifLoggedIn>
Logged in as <sec:username/>
</sec:ifLoggedIn>
<sec:ifSwitched>
<a href='${request.contextPath}/j_spring_security_exit_user'>
   Resume as <sec:switchedUserOriginalUsername/>
</a>
</sec:ifSwitched>
<sec:ifNotSwitched>
   <sec:ifAllGranted roles='ROLE_SWITCH_USER'>
   <form action='${request.contextPath}/j_spring_security_switch_user' method='POST'>
      Switch to user: <input type='text' name='j_username'/><br/>
      <input type='submit' value='Switch'/> </form>
   </sec:ifAllGranted>
</sec:ifNotSwitched>

ifNotSwitched

switchedUserOriginalUsername

<sec:ifSwitched>
<a href='${request.contextPath}/j_spring_security_exit_user'>
   Resume as <sec:switchedUserOriginalUsername/>
</a>
</sec:ifSwitched>

access

Renders the body if the specified expression evaluates to true or specified URL is allowed.

<sec:access expression="hasRole('ROLE_USER')">
You're a user
</sec:access>

<sec:access url="/admin/user">
<g:link controller='admin' action='user'>Manage Users</g:link>
</sec:access>

You can also guard access to links generated from controller and action names or named URL mappings instead of hard-coding the values, for example

<sec:access controller='admin' action='user'>
<g:link controller='admin' action='user'>Manage Users</g:link>
</sec:access>

or if you have a named URL mapping you can refer to that:

<sec:access mapping='manageUsers'>
<g:link mapping='manageUsers'>Manage Users</g:link>
</sec:access>

For even more control of the generated URL (still avoiding hard-coding) you can use createLink to build the URL, for example

<sec:access url='${createLink(controller: 'admin', action: 'user', base: "/")}'>
<g:link controller='admin' action='user'>Manage Users</g:link>
</sec:access>

Be sure to include the base: "/" attribute in this case to avoid appending the context name to the URL.

noAccess

Renders the body if the specified expression evaluates to false or URL isn't allowed.

<sec:noAccess expression="hasRole('ROLE_USER')">
You're not a user
</sec:noAccess>

link

A wrapper around the standard Grails link tag that renders if the specified expression evaluates to true or URL is allowed.

To define the expression to evaluate within the tag itself:

<sec:link controller="myController" action="myAction" expression="hasRole('ROLE_USER')">My link text</sec:link>

To use access controls defined, for example, in the interceptUrlMap:

<sec:link controller="myController" action="myAction">My link text</sec:link>

5.2 SpringSecurityService

def springSecurityService

getCurrentUser()

If you do not need domain class data other than the id, you should use the loadCurrentUser method instead.

Example:

class SomeController {
   def springSecurityService
   def someAction() {
      def user = springSecurityService.currentUser
      …
   }
}

loadCurrentUser()

If you need other data than just the id, use the getCurrentUser method instead.

Example:

class SomeController {
   def springSecurityService
   def someAction() {
      def user = springSecurityService.isLoggedIn() ?
         springSecurityService.loadCurrentUser() :
         null
      if (user) {
         CreditCard card = CreditCard.findByIdAndUser(
            params.id as Long, user)
         …
      }
      …
   }
}

isLoggedIn()

Example:

class SomeController {
   def springSecurityService
   def someAction() {
      if (springSecurityService.isLoggedIn()) {
         …
      }
      else {
         …
      }
   }
}

getAuthentication()

Retrieves the current user's Authentication. If authenticated, this will typically be a UsernamePasswordAuthenticationToken.

If not authenticated and the AnonymousAuthenticationFilter is active (true by default) then the anonymous user's authentication will be returned. This will be an instance of grails.plugin.springsecurity.authentication. GrailsAnonymousAuthenticationToken with a standard org.springframework.security.core.userdetails.User instance as its Principal. The authentication will have a single granted role, ROLE_ANONYMOUS.

Example:

class SomeController {
   def springSecurityService
   def someAction() {
      def auth = springSecurityService.authentication
      String username = auth.username
      // a Collection of GrantedAuthority
      def authorities = auth.authorities
      boolean authenticated = auth.authenticated
      …
   }
}

getPrincipal()

Retrieves the currently logged in user's Principal. If authenticated, the principal will be a grails.plugin.springsecurity.userdetails.GrailsUser, unless you have created a custom UserDetailsService, in which case it will be whatever implementation of UserDetails you use there.

If not authenticated and the AnonymousAuthenticationFilter is active (true by default) then a standard org.springframework.security.core.userdetails.User is used.

Example:

class SomeController {
   def springSecurityService
   def someAction() {
      def principal = springSecurityService.principal
      String username = principal.username
      // a Collection of GrantedAuthority
      def authorities = principal.authorities
      boolean enabled = principal.enabled
      …
   }
}

encodePassword()

You are strongly discouraged from using MD5 or SHA-1 algorithms because of their well-known vulnerabilities. You should also use a salt for your passwords, which greatly increases the computational complexity of computing passwords if your database gets compromised. See Salted Passwords.

Example:

class PersonController {
   def springSecurityService
   def updateAction() {
      def person = Person.get(params.id)
      params.salt = person.salt
      if (person.password != params.password) {
         params.password = springSecurityService.encodePassword(
            password, salt)
         def salt = … // e.g. randomly generated using a utility method
         params.salt = salt
      }
      person.properties = params
      if (!person.save(flush: true)) {
         render view: 'edit', model: [person: person]
         return
      }
      redirect action: 'show', id: person.id
   }
}

If you are hashing the password in the User domain class (using beforeInsert and encodePassword) then don't call springSecurityService.encodePassword() in your controller since you'll double-hash the password and users won't be able to log in. It's best to encapsulate the password handling logic in the domain class.

updateRole()

Example:

class RoleController {
   def springSecurityService
   def update() {
      def roleInstance = Role.get(params.id)
      if (!springSecurityService.updateRole(roleInstance, params)) {
         render view: 'edit', model: [roleInstance: roleInstance]
         return
      }
      flash.message = "The role was updated"
      redirect action: show, id: roleInstance.id
   }
}

deleteRole()

Example:

class RoleController {
   def springSecurityService
   def delete() {
      def roleInstance = Role.get(params.id)
      try {
         springSecurityService.deleteRole (roleInstance
         flash.message = "The role was deleted"
         redirect action: list
      }
      catch (DataIntegrityViolationException e) {
         flash.message = "Unable to delete the role"
         redirect action: show, id: params.id
      }
   }
}

clearCachedRequestmaps()

Example:

class RequestmapController {
   def springSecurityService
   def save() {
      def requestmapInstance = new Requestmap(params)
      if (!requestmapInstance.save(flush: true)) {
         render view: 'create',
                model: [requestmapInstance: requestmapInstance]
         return
      }
      springSecurityService.clearCachedRequestmaps()
      flash.message = "Requestmap created"
      redirect action: show, id: requestmapInstance.id
   }
}

reauthenticate()

Example:

class UserController {
   def springSecurityService
   def update() {
      def userInstance = User.get(params.id)
      params.salt = person.salt
      if (params.password) {
         params.password = springSecurityService.encodePassword(
            params.password, salt)
         def salt = … // e.g. randomly generated using a utility method
         params.salt = salt
      }
      userInstance.properties = params
      if (!userInstance.save(flush: true)) {
         render view: 'edit', model: [userInstance: userInstance]
         return
      }
      if (springSecurityService.loggedIn &&
             springSecurityService.principal.username ==
                userInstance.username) {
         springSecurityService.reauthenticate userInstance.username
      }
      flash.message = "The user was updated"
      redirect action: show, id: userInstance.id
   }
}

5.3 SpringSecurityUtils

authoritiesToRoles()

getPrincipalAuthorities()

parseAuthoritiesString()

ifAllGranted()

ifNotGranted()

ifAnyGranted()

getSecurityConfig()

loadSecondaryConfig()

reloadSecurityConfig()

isAjax()

grails.plugin.springsecurity.ajaxCheckClosure = { request ->
   // return true or false
}

You can also force the request to be treated as Ajax by appending &ajax=true to your request query string.

registerProvider()

registerFilter()

isSwitched()

getSwitchedUserOriginalUsername()

doWithAuth()

Executes a Closure with the current authentication. The one-parameter version which takes just a Closure assumes that there's an authentication in the HTTP Session and that the Closure is running in a separate thread from the web request, so the SecurityContext and Authentication aren't available to the standard ThreadLocal. This is primarily of use when you explicitly launch a new thread from a controller action or service called in request scope, not from a Quartz job which isn't associated with an authentication in any thread.

The two-parameter version takes a username and a Closure to authenticate as. This is will authenticate as the specified user and execute the closure with that authentication. It restores the authentication to the one that was active if it exists, or clears the context otherwise. This is similar to run-as and switch-user but is only local to the Closure.

6 Events

6.1 Event Notification

• Register an event listener, ignoring events that do not interest you. Spring allows only partial event subscription; you use generics to register the class of events that interest you, and you are notified of that class and all subclasses.
• Register one or more callback closures in grails-app/conf/Config.groovy that take advantage of the plugin's grails.plugin.springsecurity. SecurityEventListener. The listener does the filtering for you.

AuthenticationEventPublisher

Spring Security publishes events using an AuthenticationEventPublisher which in turn fire events using the ApplicationEventPublisher. By default no events are fired since the AuthenticationEventPublisher instance registered is a grails.plugin.springsecurity.authentication. NullAuthenticationEventPublisher. But you can enable event publishing by setting grails.plugin.springsecurity.useSecurityEventListener = true in grails-app/conf/Config.groovy.

You can use the useSecurityEventListener setting to temporarily disable and enable the callbacks, or enable them per-environment.

UsernameNotFoundException

Most authentication exceptions trigger an event with a similar name as described in this table:

This holds for all exceptions except UsernameNotFoundException which triggers an AuthenticationFailureBadCredentialsEvent just like a BadCredentialsException. This is a good idea since it doesn't expose extra information - there's no differentiation between a bad password and a missing user. In addition, by default a missing user will trigger a BadCredentialsException for the same reasons. You can configure Spring Security to re-throw the original UsernameNotFoundException instead of converting it to a BadCredentialsException by setting grails.plugin.springsecurity.dao. hideUserNotFoundExceptions = false in grails-app/conf/Config.groovy.

Fortunately all subclasses of AbstractAuthenticationFailureEvent have a getException() method that gives you access to the exception that triggered the event, so you can use that to differentiate between a bad password and a missing user (if hideUserNotFoundExceptions=false).

6.2 Registering an Event Listener

package com.foo.bar
import org.springframework.context.ApplicationListener
import org.springframework.security.authentication.event. AuthenticationSuccessEvent
class MySecurityEventListener
      implements ApplicationListener<AuthenticationSuccessEvent> {
   void onApplicationEvent(AuthenticationSuccessEvent event) {
      // handle the event
   }
}

Register the class in grails-app/conf/spring/resources.groovy:

import com.foo.bar.MySecurityEventListener
beans = {
   mySecurityEventListener(MySecurityEventListener)
}

6.3 Registering Callback Closures

Implement the event handlers that you need, for example:

grails {
  plugin {
    springsecurity {
      useSecurityEventListener = true
      onInteractiveAuthenticationSuccessEvent = { e, appCtx ->
         // handle InteractiveAuthenticationSuccessEvent
      }
      onAbstractAuthenticationFailureEvent = { e, appCtx ->
         // handle AbstractAuthenticationFailureEvent
      }
      onAuthenticationSuccessEvent = { e, appCtx ->
         // handle AuthenticationSuccessEvent
      }
      onAuthenticationSwitchUserEvent = { e, appCtx ->
         // handle AuthenticationSwitchUserEvent
      }
      onAuthorizationEvent = { e, appCtx ->
         // handle AuthorizationEvent
      }
    }
  }
}

None of these closures are required; if none are configured, nothing will be called. Just implement the event handlers that you need.

Note: When a user authenticates, Spring Security initially fires an AuthenticationSuccessEvent. This event fires before the Authentication is registered in the SecurityContextHolder, which means that the springSecurityService methods that access the logged-in user will not work. Later in the processing a second event is fired, an InteractiveAuthenticationSuccessEvent, and when this happens the SecurityContextHolder will have the Authentication. Depending on your needs, you can implement a callback for either or both events.

7 User, Authority (Role), and Requestmap Properties

8 Authentication

The default approach stores users and roles in your database, and uses an HTML login form which prompts the user for a username and password. The plugin also supports other approaches as described in the sections below, as well as add-on plugins that provide external authentication providers such as LDAP and single sign-on using CAS

8.1 Basic and Digest Authentication

grails.plugin.springsecurity.useBasicAuth = true
grails.plugin.springsecurity.basic.realmName = "Ralph's Bait and Tackle"

With this authentication in place, users are prompted with the standard browser login dialog instead of being redirected to a login page.

If you don't want all of your URLs guarded by Basic Auth, you can partition the URL patterns and apply Basic Auth to some, but regular form login to others. For example, if you have a web service that uses Basic Auth for /webservice/** URLs, you would configure that using the chainMap config attribute:

grails.plugin.springsecurity.filterChain.chainMap = [
   '/webservice/**': 'JOINED_FILTERS,-exceptionTranslationFilter',
   '/**': 'JOINED_FILTERS,-basicAuthenticationFilter,-basicExceptionTranslationFilter'
]

In this example we're using the JOINED_FILTERS keyword instead of explicitly listing the filter names. Specifying JOINED_FILTERS means to use all of the filters that were configured using the various config options. In each case we also specify that we want to exclude one or more filters by prefixing their names with -.

For the /webservice/** URLs, we want all filters except for the standard ExceptionTranslationFilter since we want to use just the one configured for Basic Auth. And for the /** URLs (everything else) we want everything except for the Basic Auth filter and its configured ExceptionTranslationFilter.

Digest Authentication is similar to Basic but is more secure because it does not send your password in obfuscated cleartext. Digest resembles Basic in practice - you get the same browser popup dialog when you authenticate. But because the credential transfer is genuinely hashed (instead of just Base64-encoded as with Basic authentication) you do not need SSL to guard your logins.

Digest authentication has a problem in that by default you store cleartext passwords in your database. This is because the browser hashes your password along with the username and Realm name, and this is compared to the password hashed using the same algorithm during authentication. The browser does not know about your MessageDigest algorithm or salt source, so to hash them the same way you need to load a cleartext password from the database.

The plugin does provide an alternative, although it has no configuration options (in particular the digest algorithm cannot be changed). If digest.useCleartextPasswords is false (the default), then the passwordEncoder bean is replaced with an instance of grails.plugin.springsecurity.authentication.encoding. DigestAuthPasswordEncoder. This encoder uses the same approach as the browser, that is, it combines your password along with your username and Realm name essentially as a salt, and hashes with MD5. MD5 is not recommended in general, but given the typical size of the salt it is reasonably safe to use.

The only required attribute is useDigestAuth, which you must set to true, but you probably also want to change the realm name:

grails.plugin.springsecurity.useDigestAuth = true
grails.plugin.springsecurity.digest.realmName = "Ralph's Bait and Tackle"

Digest authentication cannot be applied to a subset of URLs like Basic authentication can. This is due to the password encoding issues. So you cannot use the chainMap attribute here - all URLs will be guarded.

Note that since the Digest auth password encoder is different from the typical encoders you must to pass the username as the "salt" value. The generated User class uses springSecurityService which assumes you're not using a salt value. If you use the generated code in the User class to encode your password, change the dependency injection for springSecurityService with one for the passwordEncoder bean instead:

transient passwordEncoder

and change the code in encodePassword() from

password = springSecurityService.encodePassword(password)

to

password = passwordEncoder.encodePassword(password, username)

8.2 Certificate (X509) Login Authentication

The table describes available configuration options.

The details of configuring your server for SSL and configuring browser certificates are beyond the scope of this document. If you use Tomcat, see its SSL documentation. To get a test environment working, see the instructions in this discussion at Stack Overflow.

8.3 Remember-Me Cookie

You are most likely to change these attributes:

• rememberMe.cookieName. Purely aesthetic as most users will not look at their cookies, but you probably want the display name to be application-specific rather than "grails_remember_me".
• rememberMe.key. Part of a salt when the cookie is hashed. Changing the default makes it harder to execute brute-force attacks.
• rememberMe.tokenValiditySeconds. Default is two weeks; set it to what makes sense for your application.

Persistent Logins

Persistent login is also useful for authentication schemes like OpenID and Facebook, where you do not manage passwords in your database, but most of the other user information is stored locally. Without a password you cannot use the standard cookie format, so persistent logins enable remember-me cookies in these scenarios.

To use this feature, run the s2-create-persistent-token script. This will create the domain class, and register its name in grails-app/conf/Config.groovy. It will also enable persistent logins by setting rememberMe.persistent to true.

8.4 Ajax Authentication

Another option is to also have a login link on each page and to use JavaScript to present a login form within the current page in a popup. The JavaScript code submits the authentication request and displays success or error messages as appropriate.

The plugin supports Ajax logins, but you need to create your own client-side code. There are only a few necessary changes, and of course the sample code here is pretty basic so you should enhance it for your needs.

The approach here involves editing your template page(s) to show "You're logged in as ..." text if logged in and a login link if not, along with a hidden login form that is shown using JavaScript.

This example uses jQuery and jqModal, a jQuery plugin that creates and manages dialogs and popups. Download jqModal.js and copy it to grails-app/assets/javascripts, and download jqModal.css and copy it to grails-app/assets/stylesheets.

Create grails-app/assets/javascripts/ajaxLogin.js and add this JavaScript code:

var onLogin;
$.ajaxSetup({
   beforeSend: function(jqXHR, event) {
      if (event.url != $("#ajaxLoginForm").attr("action")) {
         // save the 'success' function for later use if
         // it wasn't triggered by an explicit login click
         onLogin = event.success;
      }
   },
   statusCode: {
      // Set up a global Ajax error handler to handle 401
      // unauthorized responses. If a 401 status code is
      // returned the user is no longer logged in (e.g. when
      // the session times out), so re-display the login form.
      401: function() {
         showLogin();
      }
   }
});
function showLogin() {
   var ajaxLogin = $("#ajaxLogin");
   ajaxLogin.css("text-align", "center");
   ajaxLogin.jqmShow();
}
function logout(event) {
   event.preventDefault();
   $.ajax({
      url: $("#_logout").attr("href"),
      method: "POST",
      success: function(data, textStatus, jqXHR) {
         window.location = "/";
      },
      error: function(jqXHR, textStatus, errorThrown) {
         console.log("Logout error, textStatus: " + textStatus +
                     ", errorThrown: " + errorThrown);
      }
   });
}
function authAjax() {
   $("#loginMessage").html("Sending request ...").show();
   var form = $("#ajaxLoginForm");
   $.ajax({
      url:       form.attr("action"),
      method:   "POST",
      data:      form.serialize(),
      dataType: "JSON",
      success: function(json, textStatus, jqXHR) {
         if (json.success) {
            form[0].reset();
            $("#loginMessage").empty();
            $("#ajaxLogin").jqmHide();
            $("#loginLink").html(
               'Logged in as ' + json.username +
               ' (<a href="' + $("#_logout").attr("href") +
               '" id="logout">Logout</a>)');
            $("#logout").click(logout);
            if (onLogin) {
               // execute the saved event.success function
               onLogin(json, textStatus, jqXHR);
            }
         }
         else if (json.error) {
            $("#loginMessage").html('<span class="errorMessage">' +
                                    json.error + "</error>");
         }
         else {
            $("#loginMessage").html(jqXHR.responseText);
         }
      },
      error: function(jqXHR, textStatus, errorThrown) {
         if (jqXHR.status == 401 && jqXHR.getResponseHeader("Location")) {
            // the login request itself wasn't allowed, possibly because the
            // post url is incorrect and access was denied to it
            $("#loginMessage").html('<span class="errorMessage">' +
               'Sorry, there was a problem with the login request</error>');
         }
         else {
            var responseText = jqXHR.responseText;
            if (responseText) {
               var json = $.parseJSON(responseText);
               if (json.error) {
                  $("#loginMessage").html('<span class="errorMessage">' +
                                          json.error + "</error>");
                  return;
               }
            }
            else {
               responseText = "Sorry, an error occurred (status: " +
                              textStatus + ", error: " + errorThrown + ")";
            }
            $("#loginMessage").html('<span class="errorMessage">' +
                                    responseText + "</error>");
         }
      }
   });
}
$(function() {
   $("#ajaxLogin").jqm({ closeOnEsc: true });
   $("#ajaxLogin").jqmAddClose("#cancelLogin");
   $("#ajaxLoginForm").submit(function(event) {
      event.preventDefault();
      authAjax();
   });
   $("#authAjax").click(authAjax);
   $("#logout").click(logout);
});

and create grails-app/assets/stylesheets/ajaxLogin.css and add this CSS:

#ajaxLogin {
   padding:    0px;
   text-align: center;
   display:    none;
}
#ajaxLogin .inner {
   width:              400px;
   padding-bottom:     6px;
   margin:             60px auto;
   text-align:         left;
   border:             1px solid #aab;
   background-color:   #f0f0fa;
   -moz-box-shadow:    2px 2px 2px #eee;
   -webkit-box-shadow: 2px 2px 2px #eee;
   -khtml-box-shadow:  2px 2px 2px #eee;
   box-shadow:         2px 2px 2px #eee;
}
#ajaxLogin .inner .fheader {
   padding:          18px 26px 14px 26px;
   background-color: #f7f7ff;
   margin:           0px 0 14px 0;
   color:            #2e3741;
   font-size:        18px;
   font-weight:      bold;
}
#ajaxLogin .inner .cssform p {
   clear:         left;
   margin:        0;
   padding:       4px 0 3px 0;
   padding-left:  105px;
   margin-bottom: 20px;
   height:        1%;
}
#ajaxLogin .inner .cssform input[type="text"],
#ajaxLogin .inner .cssform input[type="password"] {
   width: 150px;
}
#ajaxLogin .inner .cssform label {
   font-weight:   bold;
   float:         left;
   text-align:    right;
   margin-left:  -105px;
   width:         150px;
   padding-top:   3px;
   padding-right: 10px;
}
.ajaxLoginButton {
   background-color: #efefef;
   font-weight: bold;
   padding: 0.5em 1em;
   display: -moz-inline-stack;
   display: inline-block;
   vertical-align: middle;
   white-space: nowrap;
   overflow: visible;
   text-decoration: none;
      -moz-border-radius: 0.3em;
   -webkit-border-radius: 0.3em;
           border-radius: 0.3em;
}
.ajaxLoginButton:hover, .ajaxLoginButton:focus {
   background-color: #999999;
   color: #ffffff;
}
#ajaxLogin .inner .login_message {
   padding: 6px 25px 20px 25px;
   color:   #c33;
}
#ajaxLogin .inner .text_ {
   width: 120px;
}
#ajaxLogin .inner .chk {
   height: 12px;
}
.errorMessage {
   color: red;
}

There's no need to register the JavaScript files in grails-app/assets/javascripts/application.js if you have this require_tree directive:

//= require_tree .

but you can explicitly include them if you want. Register the two CSS files in /grails-app/assets/stylesheets/application.css:

/*
 …
 *= require ajaxLogin
 *= require jqModal
 …
 */

We'll need some GSP code to define the HTML, so create grails-app/views/includes/_ajaxLogin.gsp and add this:

<span id="logoutLink" style="display: none;">
<g:link elementId='_logout' controller='logout'>Logout</g:link>
</span>
<span id="loginLink" style="position: relative; margin-right: 30px; float: right">
<sec:ifLoggedIn>
   Logged in as <sec:username/> (<g:link elementId='logout' controller='logout'>Logout</g:link>)
</sec:ifLoggedIn>
<sec:ifNotLoggedIn>
   <a href="#" onclick="showLogin(); return false;">Login</a>
</sec:ifNotLoggedIn>
</span>
<div id="ajaxLogin" class="jqmWindow" style="z-index: 3000;">
   <div class="inner">
      <div class="fheader">Please Login..</div>
      <form action="${request.contextPath}/j_spring_security_check"
            method="POST" id="ajaxLoginForm" name="ajaxLoginForm"
            class="cssform" autocomplete="off">
         <p>
            <label for="username">Username:</label>
            <input type="text" class="text_"
                   name="j_username" id="username" />
         </p>
         <p>
            <label for="password">Password</label>
            <input type="password" class="text_"
                   name="j_password" id="password" />
         </p>
         <p>
            <label for="remember_me">Remember me</label>
            <input type="checkbox" class="chk" id="remember_me"
                   name="_spring_security_remember_me"/>
         </p>
         <p>
            <input type="submit" id="authAjax" name="authAjax"
                   value="Login" class="ajaxLoginButton" />
            <input type="button" id="cancelLogin" value="Cancel"
                   class="ajaxLoginButton" />
         </p>
      </form>
      <div style="display: none; text-align: left;" id="loginMessage"></div>
   </div>
</div>

And finally, update the grails-app/views/layouts/main.gsp layout to include _ajaxLogin.gsp, adding it after the <body> tag:

<html lang="en" class="no-js">
   <head>
      …
      <g:layoutHead/>
   </head>
   <body>
      <g:render template='/includes/ajaxLogin'/>
      …
      <g:layoutBody/>
   </body>
</html>

The important aspects of this code are:

• There is a <span> positioned in the top-right that shows the username and a logout link when logged in, and a login link otherwise.
• The form posts to the same URL as the regular form, /j_spring_security_check, and is mostly the same except for the addition of a "Cancel" button (you can also dismiss the dialog by clicking outside of it or with the escape key).
• Error messages are displayed within the popup <div>.
• Because there is no page redirect after successful login, the Javascript replaces the login link to give a visual indication that the user is logged in.
• The Logout link also uses Ajax to submit a POST request to the standard logout url and redirect you to the index page after the request finishes.
• Note that in the JavaScript logout function, you'll need to change the url in the success callback to the correct post-logout value, e.g. window.location = "/appname";

How Does Ajax login Work?

Most Ajax libraries include an X-Requested-With header that indicates that the request was made by XMLHttpRequest instead of being triggered by clicking a regular hyperlink or form submit button. The plugin uses this header to detect Ajax login requests, and uses subclasses of some of Spring Security's classes to use different redirect urls for Ajax requests than regular requests. Instead of showing full pages, LoginController has JSON-generating methods ajaxSuccess(), ajaxDenied(), and authfail() that generate JSON that the login Javascript code can use to appropriately display success or error messages.

To summarize, the typical flow would be

• click the link to display the login form
• enter authentication details and click Login
• the form is submitted using an Ajax request
• if the authentication succeeds:
• a redirect to /login/ajaxSuccess occurs (this URL is configurable)
• the rendered response is JSON and it contains two values, a boolean value success with the value true and a string value username with the authenticated user's login name
• the client determines that the login was successful and updates the page to indicate the the user is logged in; this is necessary since there's no page redirect like there would be for a non-Ajax login
• if the authentication fails:
• a redirect to /login/authfail?ajax=true occurs (this URL is configurable)
• the rendered response is JSON and it contains one value, a string value error with the displayable error message; this will be different depending on why the login was unsuccessful (bad username or password, account locked, etc.)
• the client determines that the login was not successful and displays the error message
• note that both a successful and an unsuccessful login will trigger the onSuccess Ajax callback; the onError callback will only be triggered if there's an exception or network issue

9 Authentication Providers

Use daoAuthenticationProvider to authenticate using the User and Role database tables, rememberMeAuthenticationProvider to log in with a rememberMe cookie, and anonymousAuthenticationProvider to create an 'anonymous' authentication if no other provider authenticates.

To customize this list, you define a providerNames attribute with a list of bean names. The beans must be declared either by the plugin, or yourself in resources.groovy or resources.xml. Suppose you have a custom MyAuthenticationProvider in resources.groovy:

beans = {
   myAuthenticationProvider(com.foo.MyAuthenticationProvider) {
      // attributes
   }
}

You register the provider in grails-app/conf/Config.groovy as:

grails.plugin.springsecurity.providerNames = [
   'myAuthenticationProvider',
   'anonymousAuthenticationProvider',
   'rememberMeAuthenticationProvider']

10 Custom UserDetailsService

You can extend or replace GormUserDetailsService with your own implementation by defining a bean in grails-app/conf/spring/resources.groovy (or resources.xml) with the same bean name, userDetailsService. This works because application beans are configured after plugin beans and there can only be one bean for each name. The plugin uses an extension of UserDetailsService, grails.plugin.springsecurity.userdetails. GrailsUserDetailsService, which adds the method UserDetails loadUserByUsername(String username, boolean loadRoles) to support use cases like in LDAP where you often infer all roles from LDAP but might keep application-specific user details in the database. Create the class in src/groovy and not in grails-app/services - although the interface name includes "Service", this is just a coincidence and the bean wouldn't benefit from being a Grails service.

In the following example, the UserDetails and GrailsUserDetailsService implementation adds the full name of the user domain class in addition to the standard information. If you extract extra data from your domain class, you are less likely to need to reload the user from the database. Most of your common data can be kept along with your security credentials.

This example adds in a fullName field. Keeping the full name cached avoids hitting the database just for that lookup. GrailsUser already adds the id value from the domain class to so we can do a more efficient database load of the user. If all you have is the username, then you need to call User.findByUsername(principal.username), but if you have the id you can call User.get(principal.id). Even if you have a unique index on the username database column, loading by primary key is usually more efficient because it takes advantage of Hibernate's first-level and second-level caches.

There is not much to implement other than your application-specific lookup code:

package com.mycompany.myapp
import grails.plugin.springsecurity.userdetails.GrailsUser
import org.springframework.security.core.GrantedAuthority
import org.springframework.security.core.userdetails.User
class MyUserDetails extends GrailsUser {
   final String fullName
   MyUserDetails(String username, String password, boolean enabled,
                 boolean accountNonExpired, boolean credentialsNonExpired,
                 boolean accountNonLocked,
                 Collection<GrantedAuthority> authorities,
                 long id, String fullName) {
      super(username, password, enabled, accountNonExpired,
            credentialsNonExpired, accountNonLocked, authorities, id)
      this.fullName = fullName
   }
}

package com.mycompany.myapp
import grails.plugin.springsecurity.SpringSecurityUtils
import grails.plugin.springsecurity.userdetails.GrailsUser
import grails.plugin.springsecurity.userdetails.GrailsUserDetailsService
import grails.transaction.Transactional
import org.springframework.security.core.authority.GrantedAuthorityImpl
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UsernameNotFoundException
class MyUserDetailsService implements GrailsUserDetailsService {
   /**
    * Some Spring Security classes (e.g. RoleHierarchyVoter) expect at least
    * one role, so we give a user with no granted roles this one which gets
    * past that restriction but doesn't grant anything.
    */
   static final List NO_ROLES =
      [new GrantedAuthorityImpl(SpringSecurityUtils.NO_ROLE)]
   UserDetails loadUserByUsername(String username, boolean loadRoles)
            throws UsernameNotFoundException {
      return loadUserByUsername(username)
   }
   @Transactional(readOnly=true,
        noRollbackFor=[IllegalArgumentException, UsernameNotFoundException])
   UserDetails loadUserByUsername(String username)
         throws UsernameNotFoundException {
      User user = User.findByUsername(username)
      if (!user) throw new UsernameNotFoundException(
                   'User not found', username)
      def authorities = user.authorities.collect {
         new GrantedAuthorityImpl(it.authority)
      }
      return new MyUserDetails(user.username, user.password,
         user.enabled, !user.accountExpired, !user.passwordExpired,
         !user.accountLocked, authorities ?: NO_ROLES, user.id,
         user.firstName + " " + user.lastName)
   }
}

The <code>loadUserByUsername</code> method is transactional, but read-only, to avoid lazy loading exceptions when accessing the authorities collection. There are obviously no database updates here but this is a convenient way to keep the Hibernate Session open to enable accessing the roles.

To use your implementation, register it in grails-app/conf/spring/resources.groovy like this:

beans = {
   userDetailsService(com.mycompany.myapp.MyUserDetailsService)
}

Another option for loading users and roles from the database is to subclass grails.plugin.springsecurity.userdetails. GormUserDetailsService - the methods are all protected so you can override as needed.

This approach works with all beans defined in SpringSecurityCoreGrailsPlugin.doWithSpring() - you can replace or subclass any of the Spring beans to provide your own functionality when the standard extension mechanisms are insufficient.

Flushing the Cached Authentication

class MyController {
   def springSecurityService
   def someAction() {
      def user = …
      // update user data
      user.save()
      springSecurityService.reauthenticate user.username
      …
   }
}

11 Password and Account Protection

11.1 Password Hashing

bcrypt is a much more secure alternative to the message digest approaches since it supports a customizable work level which when increased takes more computation time to hash the users' passwords, but also dramatically increases the cost of brute force attacks. Given how easy it is to use GPUs to crack passwords, you should definitely consider using bcrypt for new projects and switching to it for existing projects. Note that due to the approach used by bcrypt, you cannot add an additional salt like you can with the message digest algorithms.

Enable bcrypt by using the 'bcrypt' value for the algorithm config attribute:

grails.plugin.springsecurity.password.algorithm = 'bcrypt'

and optionally changing the number of rekeying rounds (which will affect the time it takes to hash passwords), e.g.

grails.plugin.springsecurity.password.bcrypt.logrounds = 15

Note that the number of rounds must be between 4 and 31.

PBKDF2 is also supported.

The table shows configurable password hashing attributes.

If you want to use a message digest hashing algorithm, see this Java page for the available algorithms.

11.2 Salted Passwords

Note that if you use bcrypt (the default setting) or pbkdf2, do not configure a salt (e.g. the dao.reflectionSaltSourceProperty property or a custom saltSource bean) because these algorithms use their own internally.

There are two approaches to using salted passwords in the plugin - defining a field in the UserDetails class to access by reflection, or by directly implementing SaltSource yourself.

dao.reflectionSaltSourceProperty

grails.plugin.springsecurity.dao.reflectionSaltSourceProperty = 'username'

This property belongs to the UserDetails class. By default it is an instance of grails.plugin.springsecurity.userdetails.GrailsUser, which extends the standard Spring Security User class and not your 'person' domain class. This limits the available fields unless you use a custom UserDetailsService.

As long as the username does not change, this approach works well for the salt. If you choose a property that the user can change, the user cannot log in again after changing it unless you re-hash the password with the new value. So it's best to use a property that doesn't change.

Another option is to generate a random salt when creating users and store this in the database by adding a new field to the 'person' class. This approach requires a custom UserDetailsService because you need a custom UserDetails implementation that also has a 'salt' property, but this is more flexible and works in cases where users can change their username.

SystemWideSaltSource and Custom SaltSource

Spring Security supplies a simple SaltSource implementation, SystemWideSaltSource, which uses the same salt for each user. It's less robust than using a different value for each user but still better than no salt at all.

An example override of the salt source bean using SystemWideSaltSource would look like this:

import org.springframework.security.authentication.dao.SystemWideSaltSource
beans = {
   saltSource(SystemWideSaltSource) {
      systemWideSalt = 'the_salt_value'
   }
}

To have full control over the process, you can implement the SaltSource interface and replace the plugin's implementation with your own by defining a bean in grails-app/conf/spring/resources.groovy with the name saltSource:

beans = {
   saltSource(com.foo.bar.MySaltSource) {
      // set properties
   }
}

Hashing Passwords

class UserController {
   def springSecurityService
   def save() {
      def userInstance = new User(params)
      userInstance.password = springSecurityService.encodePassword(
                    params.password, userInstance.username)
      if (!userInstance.save(flush: true)) {
         render view: 'create', model: [userInstance: userInstance]
         return
      }
      flash.message = "The user was created"
      redirect action: show, id: userInstance.id
   }
   def update() {
      def userInstance = User.get(params.id)
      if (params.password) {
         params.password = springSecurityService.encodePassword(
                    params.password, userInstance.username)
      }
      userInstance.properties = params
      if (!userInstance.save(flush: true)) {
         render view: 'edit', model: [userInstance: userInstance]
         return
      }
      if (springSecurityService.loggedIn &&
               springSecurityService.principal.username ==
                  userInstance.username) {
         springSecurityService.reauthenticate userInstance.username
      }
      flash.message = "The user was updated"
      redirect action: show, id: userInstance.id
   }
}

If you are encoding the password in the User domain class (using beforeInsert and encodePassword) then don't call springSecurityService.encodePassword() in your controller since you'll double-hash the password and users won't be able to log in. It's best to encapsulate the password handling logic in the domain class. In newer versions of the plugin (version 1.2 and higher) code is auto-generated in the user class so you'll need to adjust that password hashing for your salt approach.

11.3 Account Locking and Forcing Password Change

• isAccountNonExpired()
• isAccountNonLocked()
• isCredentialsNonExpired()
• isEnabled()

If you use the s2-quickstart script to create a user domain class, it creates a class with corresponding properties to manage this state.

When an accessor returns true for accountExpired, accountLocked, or passwordExpired or returns false for enabled, a corresponding exception is thrown:

You can configure an exception mapping in Config.groovy to associate a URL to any or all of these exceptions to determine where to redirect after a failure, for example:

grails.plugin.springsecurity.failureHandler.exceptionMappings = [
   'org.springframework.security.authentication.LockedException':
      '/user/accountLocked',
   'org.springframework.security.authentication.DisabledException':
      '/user/accountDisabled',
   'org.springframework.security.authentication.AccountExpiredException':
      '/user/accountExpired',
   'org.springframework.security.authentication.CredentialsExpiredException':
      '/user/passwordExpired'
]

Without a mapping for a particular exception, the user is redirected to the standard login fail page (by default /login/authfail), which displays an error message from this table:

You can customize these messages by setting the corresponding property in Config.groovy, for example:

grails.plugin.springsecurity.errors.login.locked = "None shall pass."

You can use this functionality to manually lock a user's account or expire the password, but you can automate the process. For example, use the Quartz plugin to periodically expire everyone's password and force them to go to a page where they update it. Keep track of the date when users change their passwords and use a Quartz job to expire their passwords once the password is older than a fixed max age.

Here's an example for a password expired workflow. You'd need a simple action to display a password reset form (similar to the login form):

def passwordExpired() {
   [username: session['SPRING_SECURITY_LAST_USERNAME']]
}

and the form would look something like this:

<div id='login'>
   <div class='inner'>
      <g:if test='${flash.message}'>
      <div class='login_message'>${flash.message}</div>
      </g:if>
      <div class='fheader'>Please update your password..</div>
      <g:form action='updatePassword' id='passwordResetForm'
              class='cssform' autocomplete='off'>
         <p>
            <label for='username'>Username</label>
            <span class='text_'>${username}</span>
         </p>
         <p>
            <label for='password'>Current Password</label>
            <g:passwordField name='password' class='text_' />
         </p>
         <p>
            <label for='password'>New Password</label>
            <g:passwordField name='password_new' class='text_' />
         </p>
         <p>
            <label for='password'>New Password (again)</label>
            <g:passwordField name='password_new_2' class='text_' />
         </p>
         <p>
            <input type='submit' value='Reset' />
         </p>
      </g:form>
   </div>
</div>

It's important that you not allow the user to specify the username (it's available in the HTTP session) but that you require the current password, otherwise it would be simple to forge a password reset.

The GSP form would submit to an action like this one:

def updatePassword() {
   String username = session['SPRING_SECURITY_LAST_USERNAME']
   if (!username) {
      flash.message = 'Sorry, an error has occurred'
      redirect controller: 'login', action: 'auth'
      return
   }
   String password = params.password
   String newPassword = params.password_new
   String newPassword2 = params.password_new_2
   if (!password || !newPassword || !newPassword2 ||
        newPassword != newPassword2) {
      flash.message =
         'Please enter your current password and a valid new password'
      render view: 'passwordExpired',
             model: [username: session['SPRING_SECURITY_LAST_USERNAME']]
      return
   }
   User user = User.findByUsername(username)
   if (!passwordEncoder.isPasswordValid(user.password,
         password, null /*salt*/)) {
      flash.message = 'Current password is incorrect'
      render view: 'passwordExpired',
             model: [username: session['SPRING_SECURITY_LAST_USERNAME']]
      return
   }
   if (passwordEncoder.isPasswordValid(user.password, newPassword,
         null /*salt*/)) {
      flash.message =
         'Please choose a different password from your current one'
      render view: 'passwordExpired',
             model: [username: session['SPRING_SECURITY_LAST_USERNAME']]
      return
   }
   user.password = newPassword
   user.passwordExpired = false
   user.save() // if you have password constraints check them here
   redirect controller: 'login', action: 'auth'
}

User Cache

If you enable this feature, you must remove any cached instances after making a change that affects login. If you do not remove cached instances, even though a user's account is locked or disabled, logins succeed because the database is bypassed. By removing the cached data, you force at trip to the database to retrieve the latest updates.

Here is a sample Quartz job that demonstrates how to find and disable users with passwords that are too old:

package com.mycompany.myapp
class ExpirePasswordsJob {
   static triggers = {
      cron name: 'myTrigger', cronExpression: '0 0 0 * * ?' // midnight daily
   }
   def userCache
   void execute() {
      def users = User.executeQuery(
            'from User u where u.passwordChangeDate <= :cutoffDate',
            [cutoffDate: new Date() - 180])
      for (user in users) {
         // flush each separately so one failure
         // doesn't rollback all of the others
         try {
            user.passwordExpired = true
            user.save(flush: true)
            userCache.removeUserFromCache user.username
         }
         catch (e) {
            log.error "problem expiring password for user $user.username : $e.message", e
         }
      }
   }
}

12 URL Properties

13 Hierarchical Roles

For example, if you have several types of 'admin' roles that can be used to access a URL pattern and you do not use hierarchical roles, you need to specify all the admin roles:

package com.mycompany.myapp
import grails.plugin.springsecurity.annotation.Secured
class SomeController {
   @Secured(['ROLE_ADMIN', 'ROLE_FINANCE_ADMIN', 'ROLE_SUPERADMIN'])
   def someAction() {
      …
   }
}

However, if you have a business rule that says ROLE_FINANCE_ADMIN implies being granted ROLE_ADMIN, and that ROLE_SUPERADMIN implies being granted ROLE_FINANCE_ADMIN, you can express that hierarchy as:

grails.plugin.springsecurity.roleHierarchy = '''
   ROLE_SUPERADMIN > ROLE_FINANCE_ADMIN
   ROLE_FINANCE_ADMIN > ROLE_ADMIN
'''

Then you can simplify your mappings by specifying only the roles that are required:

package com.mycompany.myapp
import grails.plugin.springsecurity.annotation.Secured
class SomeController {
   @Secured(['ROLE_ADMIN'])
   def someAction() {
      …
   }
}

You can also reduce the number of granted roles in the database. Where previously you had to grant ROLE_SUPERADMIN, ROLE_FINANCE_ADMIN, and ROLE_ADMIN, now you only need to grant ROLE_SUPERADMIN.

14 Switch User

This feature is very powerful; it allows full access to everything the switched-to user can access without requiring the user's password. Limit who can use this feature by guarding the user switch URL with a role, for example, ROLE_SWITCH_USER, ROLE_ADMIN, and so on.

Switching to Another User

To switch to another user, typically you create a form that submits to /j_spring_security_switch_user:

<sec:ifAllGranted roles='ROLE_SWITCH_USER'>
   <form action='/j_spring_security_switch_user' method='POST'>
      Switch to user: <input type='text' name='j_username'/> <br/>
      <input type='submit' value='Switch'/>
   </form>
</sec:ifAllGranted>

Here the form is guarded by a check that the logged-in user has ROLE_SWITCH_USER and is not shown otherwise. You also need to guard the user switch URL, and the approach depends on your mapping scheme. If you use annotations, add a rule to the controllerAnnotations.staticRules attribute:

grails.plugin.springsecurity.controllerAnnotations.staticRules = [
   …
   '/j_spring_security_switch_user':
      ['ROLE_SWITCH_USER', 'isFullyAuthenticated()']
]

If you use Requestmaps, create a rule like this (for example, in BootStrap):

new Requestmap(url: '/j_spring_security_switch_user',
               configAttribute: 'ROLE_SWITCH_USER,isFullyAuthenticated()'
               ).save(flush: true)

If you use the Config.groovy map, add the rule there:

grails.plugin.springsecurity.interceptUrlMap = [
   …
   '/j_spring_security_switch_user':
      ['ROLE_SWITCH_USER', 'isFullyAuthenticated()']
]

Switching Back to Original User

<sec:ifSwitched>
<a href='${request.contextPath}/j_spring_security_exit_user'>
   Resume as <sec:switchedUserOriginalUsername/>
</a>
</sec:ifSwitched>

Customizing URLs

grails.plugin.springsecurity.switchUser.switchUserUrl = …
grails.plugin.springsecurity.switchUser.exitUserUrl = …
grails.plugin.springsecurity.switchUser.targetUrl = …
grails.plugin.springsecurity.switchUser.switchFailureUrl = ...

GSP Code

One approach to supporting the switch user feature is to add code to one or more of your GSP templates. In this example the current username is displayed, and if the user has switched from another (using the sec:ifSwitched tag) then a 'resume' link is displayed. If not, and the user has the required role, a form is displayed to allow input of the username to switch to:

<sec:ifLoggedIn>
Logged in as <sec:username/>
</sec:ifLoggedIn>
<sec:ifSwitched>
<a href='${request.contextPath}/j_spring_security_exit_user'>
   Resume as <sec:switchedUserOriginalUsername/>
</a>
</sec:ifSwitched>
<sec:ifNotSwitched>
   <sec:ifAllGranted roles='ROLE_SWITCH_USER'>
   <form action='${request.contextPath}/j_spring_security_switch_user'
         method='POST'>
      Switch to user: <input type='text' name='j_username'/><br/>
      <input type='submit' value='Switch'/>
   </form>
   </sec:ifAllGranted>
</sec:ifNotSwitched>

15 Filters

Default Approach to Configuring Filter Chains

filterNames

For example:

grails.plugin.springsecurity.filterChain.filterNames = [
   'securityContextPersistenceFilter', 'logoutFilter',
   'authenticationProcessingFilter', 'myCustomProcessingFilter',
   'rememberMeAuthenticationFilter', 'anonymousAuthenticationFilter',
   'exceptionTranslationFilter', 'filterInvocationInterceptor'
]

This example creates a filter chain corresponding to the Spring beans with the specified names.

chainMap

grails.plugin.springsecurity.filterChain.chainMap = [
   '/urlpattern1/**': 'filter1,filter2,filter3,filter4',
   '/urlpattern2/**': 'filter1,filter3,filter5',
   '/**': 'JOINED_FILTERS',
]

In this example, four filters are applied to URLs matching /urlpattern1/** and three different filters are applied to URLs matching /urlpattern2/**. In addition the special token JOINED_FILTERS is applied to all URLs. This is a conventient way to specify that all defined filters (configured either with configuration rules like useSwitchUserFilter or explicitly using filterNames) should apply to this pattern.

The order of the mappings is important. Each URL will be tested in order from top to bottom to find the first matching one. So you need a /** catch-all rule at the end for URLs that do not match one of the earlier rules.

There's also a filter negation syntax that can be very convenient. Rather than specifying all of the filter names (and risking forgetting one or putting them in the wrong order), you can use the JOINED_FILTERS keyword and one or more filter names prefixed with a -. This means to use all configured filters except for the excluded ones. For example, if you had a web service that uses Basic Auth for /webservice/** URLs, you would configure that using:

grails.plugin.springsecurity.filterChain.chainMap = [
   '/webservice/**': 'JOINED_FILTERS,-exceptionTranslationFilter',
   '/**': 'JOINED_FILTERS,-basicAuthenticationFilter,-basicExceptionTranslationFilter'
]

For the /webservice/** URLs, we want all filters except for the standard ExceptionTranslationFilter since we want to use just the one configured for Basic Auth. And for the /** URLs (everything else) we want everything except for the Basic Auth filter and its configured ExceptionTranslationFilter.

Additionally, you can use a chainMap configuration to declare one or more URL patterns which should have no filters applied. Use the name 'none' for these patterns, e.g.

grails.plugin.springsecurity.filterChain.chainMap = [
   '/someurlpattern/**': 'none',
   '/**': 'JOINED_FILTERS'
]

clientRegisterFilter

beans = {
   myFilter(com.mycompany.myapp.MyFilter) {
      // properties
   }
}

and then register it in grails-app/conf/BootStrap.groovy:

import grails.plugin.springsecurity.SecurityFilterPosition
import grails.plugin.springsecurity.SpringSecurityUtils
class BootStrap {
   def init = {
      SpringSecurityUtils.clientRegisterFilter(
          'myFilter', SecurityFilterPosition.OPENID_FILTER.order + 10)
   }
}

This bootstrap code registers your filter just after the Open ID filter (if it's configured). You cannot register a filter in the same position as another, so it's a good idea to add a small delta to its position to put it after or before a filter that it should be next to in the chain. The Open ID filter position is just an example - add your filter in the position that makes sense.

16 Channel Security

Build a Map under the secureChannel.definition key, where the keys are URL patterns, and the values are one of REQUIRES_SECURE_CHANNEL, REQUIRES_INSECURE_CHANNEL, or ANY_CHANNEL:

grails.plugin.springsecurity.secureChannel.definition = [
   '/login/**':         'REQUIRES_SECURE_CHANNEL',
   '/maps/**':          'REQUIRES_INSECURE_CHANNEL',
   '/images/login/**':  'REQUIRES_SECURE_CHANNEL',
   '/images/**':        'ANY_CHANNEL'
]

URLs are checked in order, so be sure to put more specific rules before less specific. In the preceding example, /images/login/** is more specific than /images/**, so it appears first in the configuration.

Header checking

The default implementation of channel security is fairly simple; if you're using HTTP but HTTPS is required, you get redirected to the corresponding SSL URL and vice versa. But when using a load balancer such as an F5 BIG-IP it's not possible to just check secure/insecure. In that case you can configure the load balancer to set a request header indicating the current state. To use this approach, set the useHeaderCheckChannelSecurity configuration property to true and optionally change the header names or values:

grails.plugin.springsecurity.secureChannel.useHeaderCheckChannelSecurity = true

By default the header name is "X-Forwarded-Proto" and the secure header value is "http" (i.e. if you're not secure, redirect to secure) and the insecure header value is "https" (i.e. if you're secure, redirect to insecure). You can change any or all of these default values though:

grails.plugin.springsecurity.secureChannel.secureHeaderName = '...'
grails.plugin.springsecurity.secureChannel.secureHeaderValue = '...'
grails.plugin.springsecurity.secureChannel.insecureHeaderName = '...'
grails.plugin.springsecurity.secureChannel.insecureHeaderValue = '...'

17 IP Address Restrictions

For example, make an admin-only part of your site accessible only from IP addresses of the local LAN or VPN, such as 192.168.1.xxx or 10.xxx.xxx.xxx. You can also set this up at your firewall and/or routers, but it is convenient to encapsulate it within your application.

To use this feature, specify an ipRestrictions configuration map, where the keys are URL patterns, and the values are IP address patterns that can access those URLs. The IP patterns can be single-value strings, or multi-value lists of strings. They can use CIDR masks, and can specify either IPv4 or IPv6 patterns. For example, given this configuration:

grails.plugin.springsecurity.ipRestrictions = [
   '/pattern1/**': '123.234.345.456',
   '/pattern2/**': '10.0.0.0/8',
   '/pattern3/**': ['10.10.200.42', '10.10.200.63']
]

pattern1 URLs can be accessed only from the external address 123.234.345.456, pattern2 URLs can be accessed only from a 10.xxx.xxx.xxx intranet address, and pattern3 URLs can be accessed only from 10.10.200.42 or 10.10.200.63. All other URL patterns are accessible from any IP address.

All addresses can always be accessed from localhost regardless of IP pattern, primarily to support local development mode.

You cannot compare IPv4 and IPv6 addresses, so if your server supports both, you need to specify the IP patterns using the address format that is actually being used. Otherwise the filter throws exceptions. One option is to set the java.net.preferIPv4Stack system property, for example, by adding it to JAVA_OPTS or GRAILS_OPTS as -Djava.net.preferIPv4Stack=true.

18 Session Fixation Prevention

grails.plugin.springsecurity.useSessionFixationPrevention = true

Upon successful authentication a new HTTP session is created and the previous session's attributes are copied into it. If you start your session by clicking a link that was generated by someone trying to hack your account, which contained an active session id, you are no longer sharing the previous session after login. You have your own session.

Session fixation is less of a problem now that Grails by default does not include jsessionid in URLs (see this JIRA issue), but it's still a good idea to use this feature.

Note that there is an issue when using the cookie-session plugin; see this issue for more details.

The table shows configuration options for session fixation.

19 Logout Handlers

By default, a securityContextLogoutHandler bean is registered to clear the SecurityContextHolder. Also, unless you are using Facebook or OpenID, rememberMeServices bean is registered to reset your cookie. (Facebook and OpenID authenticate externally so we don't have access to the password to create a remember-me cookie.) If you are using Facebook, a facebookLogoutHandler is registered to reset its session cookies.

To customize this list, you define a logout.handlerNames attribute with a list of bean names.

The beans must be declared either by the plugin or by you in resources.groovy or resources.xml. For example, suppose you have a custom MyLogoutHandler in resources.groovy:

beans = {
   myLogoutHandler(com.foo.MyLogoutHandler) {
      // attributes
   }
}

You register it in grails-app/conf/Config.groovy as:

grails.plugin.springsecurity.logout.handlerNames = [
   'rememberMeServices', 'securityContextLogoutHandler', 'myLogoutHandler'
]

20 Voters

By default a roleVoter bean is registered to ensure users have the required roles for the request, and an authenticatedVoter bean is registered to support IS_AUTHENTICATED_FULLY, IS_AUTHENTICATED_REMEMBERED, and IS_AUTHENTICATED_ANONYMOUSLY tokens.

To customize this list, you define a voterNames attribute with a list of bean names. The beans must be declared either by the plugin, or yourself in resources.groovy or resources.xml. Suppose you have a custom MyAccessDecisionVoter in resources.groovy:

beans = {
   myAccessDecisionVoter(com.foo.MyAccessDecisionVoter) {
      // attributes
   }
}

You register it in grails-app/conf/Config.groovy as:

grails.plugin.springsecurity.voterNames = [
   'authenticatedVoter', 'roleVoter',
   'webExpressionVoter', 'myAccessDecisionVoter'
]

21 Miscellaneous Properties

22 Tutorials

22.1 Using Controller Annotations to Secure URLs

1. Create your Grails application.

$ grails create-app bookstore
$ cd bookstore

2. Install the plugin by adding it to BuildConfig.groovy

plugins {
   …
   compile ':spring-security-core:2.0.0'
}

Run the compile script to resolve the dependencies and ensure everything is correct:

$ grails compile

3. Create the User and Role domain classes.

$ grails s2-quickstart com.testapp User Role

You can choose your names for your domain classes and package; these are just examples.

Depending on your database, some domain class names might not be valid, especially those relating to security. Before you create names like "User" or "Group", make sure they are not reserved keywords in your database. or escape the name with backticks in the mapping block, e.g.

static mapping = {
   table '`user`'
}

The script creates this User class:

package com.testapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='username')
@ToString(includes='username', includeNames=true, includePackage=false)
class User implements Serializable {
   private static final long serialVersionUID = 1
   transient springSecurityService
   String username
   String password
   boolean enabled = true
   boolean accountExpired
   boolean accountLocked
   boolean passwordExpired
   User(String username, String password) {
      this()
      this.username = username
      this.password = password
   }
   Set<Role> getAuthorities() {
      UserRole.findAllByUser(this)*.role
   }
   def beforeInsert() {
      encodePassword()
   }
   def beforeUpdate() {
      if (isDirty('password')) {
         encodePassword()
      }
   }
   protected void encodePassword() {
      password = springSecurityService?.passwordEncoder ?
         springSecurityService.encodePassword(password) :
         password
   }
   static transients = ['springSecurityService']
   static constraints = {
      username blank: false, unique: true
      password blank: false
   }
   static mapping = {
      password column: '`password`'
   }
}

Earlier versions of the plugin didn't include password hashing logic in the domain class, but it makes the code a lot cleaner.

and this Role class:

package com.testapp
import groovy.transform.EqualsAndHashCode
import groovy.transform.ToString
@EqualsAndHashCode(includes='authority')
@ToString(includes='authority', includeNames=true, includePackage=false)
class Role implements Serializable {
   private static final long serialVersionUID = 1
   String authority
   Role(String authority) {
      this()
      this.authority = authority
   }
   static constraints = {
      authority blank: false, unique: true
   }
   static mapping = {
      cache true
   }
}

and a domain class that maps the many-to-many join class, UserRole:

package com.testapp
import grails.gorm.DetachedCriteria
import groovy.transform.ToString
import org.apache.commons.lang.builder.HashCodeBuilder
@ToString(cache=true, includeNames=true, includePackage=false)
class UserRole implements Serializable {
   private static final long serialVersionUID = 1
   User user
   Role role
   UserRole(User u, Role r) {
      this()
      user = u
      role = r
   }
   @Override
   boolean equals(other) {
      if (!(other instanceof UserRole)) {
         return false
      }
      other.user?.id == user?.id && other.role?.id == role?.id
   }
   @Override
   int hashCode() {
      def builder = new HashCodeBuilder()
      if (user) builder.append(user.id)
      if (role) builder.append(role.id)
      builder.toHashCode()
   }
   static UserRole get(long userId, long roleId) {
      criteriaFor(userId, roleId).get()
   }
   static boolean exists(long userId, long roleId) {
      criteriaFor(userId, roleId).count()
   }
   private static DetachedCriteria criteriaFor(long userId, long roleId) {
      UserRole.where {
         user == User.load(userId) &&
         role == Role.load(roleId)
      }
   }
   static UserRole create(User user, Role role, boolean flush = false) {
      def instance = new UserRole(user: user, role: role)
      instance.save(flush: flush, insert: true)
      instance
   }
   static boolean remove(User u, Role r, boolean flush = false) {
      if (u == null || r == null) return false
      int rowCount = UserRole.where { user == u && role == r }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
      rowCount
   }
   static void removeAll(User u, boolean flush = false) {
      if (u == null) return
      UserRole.where { user == u }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
   }
   static void removeAll(Role r, boolean flush = false) {
      if (r == null) return
      UserRole.where { role == r }.deleteAll()
      if (flush) { UserRole.withSession { it.flush() } }
   }
   static constraints = {
      role validator: { Role r, UserRole ur ->
         if (ur.user == null || ur.user.id == null) return
         boolean existing = false
         UserRole.withNewSession {
            existing = UserRole.exists(ur.user.id, r.id)
         }
         if (existing) {
            return 'userRole.exists'
         }
      }
   }
   static mapping = {
      id composite: ['user', 'role']
      version false
   }
}

The script has edited grails-app/conf/Config.groovy and added the configuration for your domain classes. Make sure that the changes are correct.

These generated files are not part of the plugin - these are your application files. They are examples to get you started, so you can edit them as you please. They contain the minimum needed for the plugin's default implementation of the Spring Security UserDetailsService (which like everything in the plugin is customizable).

The plugin has no support for CRUD actions or GSPs for your domain classes; the spring-security-ui plugin supplies a UI for those. So for now you will create roles and users in grails-app/conf/BootStrap.groovy. (See step 7.)

4. Create a controller that will be restricted by role.

$ grails create-controller com.testapp.Secure

This command creates grails-app/controllers/com/testapp/ SecureController.groovy. Add some output so you can verify that things are working:

package com.testapp
class SecureController {
   def index() {
      render 'Secure access only'
   }
}

5. Edit grails-app/conf/BootStrap.groovy to add a test user.

import com.testapp.Role
import com.testapp.User
import com.testapp.UserRole
class BootStrap {
   def init = { servletContext ->
      def adminRole = new Role('ROLE_ADMIN').save()
      def userRole = new Role('ROLE_USER').save()
      def testUser = new User('me', 'password').save()
      UserRole.create testUser, adminRole, true
      assert User.count() == 1
      assert Role.count() == 2
      assert UserRole.count() == 1
   }
}

Some things to note about the preceding BootStrap.groovy:

• The example does not use a traditional GORM many-to-many mapping for the User<->Role relationship; instead you are mapping the join table with the UserRole class. This performance optimization helps significantly when many users have one or more common roles.
• We explicitly flush (using the 3-arg UserRole.create() call) because BootStrap does not run in a transaction or OpenSessionInView.

6. Start the server.

$ grails run-app

7. Before you secure the page, navigate to http://localhost:8080/bookstore/secure to verify that you cannot access see the page yet. You will be redirected to the login page, but after a successful authentication (log in with the username and password you used for the test user in BootStrap.groovy) you will see an error page:

Sorry, you're not authorized to view this page.

This is because with the default configuration, all URLs are denied unless there is an access rule specified.

8. Edit grails-app/controllers/SecureController.groovy to import the annotation class and apply the annotation to restrict (and grant) access.

package com.testapp
import grails.plugin.springsecurity.annotation.Secured
class SecureController {
   @Secured('ROLE_ADMIN')
   def index() {
      render 'Secure access only'
   }
}

or

@Secured('ROLE_ADMIN')
class SecureController {
   def index() {
      render 'Secure access only'
   }
}

You can annotate the entire controller or individual actions. In this case you have only one action, so you can do either.

9. Shut down the app and run grails run-app again, and navigate again to http://localhost:8080/bookstore/secure.

This time you should again be able to see the secure page after successfully authenticating.

10. Test the Remember Me functionality.

11. Optionally, create a CRUD UI to work with users and roles.

Run grails generate-all for the domain classes:

$ grails generate-all com.testapp.User

$ grails generate-all com.testapp.Role

Since the User domain class handles password hashing, there are no changes required in the generated controllers.

23 Controller MetaClass Methods

isLoggedIn

Returns true if there is an authenticated user.

class MyController {
   def someAction() {
      if (isLoggedIn()) {
         …
      }
      ...
      if (!isLoggedIn()) {
         …
      }
      // or
      if (loggedIn) {
         …
      }
      if (!loggedIn) {
         …
      }
   }
}

getPrincipal

Retrieves the current authenticated user's Principal (a GrailsUser instance unless you've customized this) or null if not authenticated.

class MyController {
   def someAction() {
      if (isLoggedIn()) {
         String username = getPrincipal().username
         …
      }
      // or
      if (isLoggedIn()) {
         String username = principal.username
         …
      }
   }
}

getAuthenticatedUser

Loads the user domain class instance from the database that corresponds to the currently authenticated user, or null if not authenticated. This is the equivalent of adding a dependency injection for springSecurityService and calling PersonDomainClassName.get(springSecurityService.principal.id) (the typical way that this is often done).

class MyController {
   def someAction() {
      if (isLoggedIn()) {
         String email = getAuthenticatedUser().email
         …
      }
      // or
      if (isLoggedIn()) {
         String email = authenticatedUser.email
         …
      }
   }
}

24 Internationalization

If you want to customize or translate the texts then add messages for the following keys to your i18n resource bundle(s) for each exception:

You can customize all messages in auth.gsp and denied.gsp: