Spring Security Core Plugin - Reference Documentation

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

The Spring Security plugin maintains its configuration in grails-app/conf/application.groovy, although you can keep the plugin config in application.yml with the rest of the configuration if you prefer. Default values are in the plugin’s grails-app/conf/DefaultSecurityConfig.groovy file, and you add application-specific values to application.groovy (or application.yml). The default configuration is merged with your settings, with application values overriding the defaults and setting missing values.

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.

Once you install the plugin, you simply run the initialization script, s2-quickstart, and make any required configuration changes in application.groovy / application.yml. The plugin registers its servlet API configuration (the Spring Security filter chain, etc.) programmatically, not in web.xml as was the case in earlier versions, and also configures the Spring beans in the application context that implement various pieces of functionality. Dependency management determines which jar files to use.

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

You do not need deep knowledge of Spring Security to use the plugin, but it is helpful to understand the underlying implementation. See the Spring Security documentation.

Version 4.0.1 of the plugin switched back to "MODE_THREADLOCAL" as the default strategy. This means that newly created threads do not inherit the security context of the parent thread.

In Grails 2, configuration settings were stored in grails-app/conf/Config.groovy, but they’re in YAML format in grails-app/conf/application.yml now. You can use the Groovy ConfigObject style if you want, in grails-app/conf/application.groovy. The file isn’t created by the create-app script but if you create it manually it will be recognized. When you run any of the plugin scripts, settings are added in application.groovy (it will be created if necessary) but if you prefer to keep your settings in YAML format, feel free to move them to application.yml. Note that this won’t work for values that aren’t supported in YAML format, for example Closures or other Java or Groovy objects.

Version 3.2.1 of the plugin now uses "MODE_INHERITABLETHREADLOCAL" as the default strategy. This means that newly created threads inherit the security context of the parent thread.

In Grails 2, configuration settings were stored in grails-app/conf/Config.groovy, but they’re in YAML format in grails-app/conf/application.yml now. You can use the Groovy ConfigObject style if you want, in grails-app/conf/application.groovy. The file isn’t created by the create-app script but if you create it manually it will be recognized. When you run any of the plugin scripts, settings are added in application.groovy (it will be created if necessary) but if you prefer to keep your settings in YAML format, feel free to move them to application.yml. Note that this won’t work for values that aren’t supported in YAML format, for example Closures or other Java or Groovy objects.

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.

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

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 in Configuring Request Mappings to Secure URLs.

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.

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:

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.

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.

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

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.

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

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 grails-app/conf/application.yml

Also add the implementation class name in your logback configuration:

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.

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.

Spring Security uses an Authentication object to determine whether the current user is allowed to perform a secured action, such as accessing a URL, manipulating a secured domain object, invoking a secured method, and so on. This object is created during login. Typically overlap occurs between the need for authentication data and the need to represent a user in the application in ways that are unrelated to security. The mechanism for populating the authentication is completely pluggable in Spring Security; you only need to provide an implementation of UserDetailsService and implement its one method, loadUserByUsername(String username).

By default the plugin uses a Grails “person” domain class to manage this data. username, enabled, and password are the default names of the core required properties. You can easily plug in your own implementation (Custom UserDetailsService), and rename the class, package, and properties. In addition, you should define an authorities property to retrieve roles; this can be a property 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:

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

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:

The Spring Security plugin uses an “authority” class to represent a user’s roles in the application. In general this class restricts URLs to users who have been assigned the required access rights. A user can be granted multiple roles to indicate various access rights in the application, and should have at least one. A basic user who can access only non-restricted resources but can still authenticate is a bit unusual. Spring Security usually functions fine if a user has no granted authorities, but fails in a few places that assume one or more. So if a user authenticates successfully but has no granted roles, the plugin grants the user a “virtual” role, ROLE_NO_ROLES. Thus the user satisfies Spring Security’s requirements but cannot access secure resources, as you would not associate any secure resources with this role.

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/application.groovy.

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

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

The typical approach to mapping the relationship between “person” and “authority” is a many-to-many. Users have multiple roles, and roles are shared by multiple users. This approach can be problematic in Grails, because a popular role, for example, ROLE_USER, will be granted to many users in your application. GORM uses collections to manage adding and removing related instances and maps many-to-many relationships bidirectionally. Granting a role to a user requires loading all existing users who have that role because the collection is a Set. So even though no uniqueness concerns may exist, Hibernate loads them all to enforce uniqueness. The recommended approach in the plugin is to map a domain class to the join table that manages the many-to-many, and using that to grant and revoke roles to users.

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:

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:

Revoking a role is similar:

The class name is the only configurable attribute:

The plugin provides you the option of creating an access inheritance level between “person” and “authority”: the “group”. The next three classes you will read about (including this one) are only used in a “person”/“group”/“authority” implementation. Rather than granting authorities directly to a “person”, you can create a “group”, map authorities to it, and then map a “person” to that “group”. For applications that have a one or more groups of users who need the same level of access, having one or more “group” instances makes managing changes to access levels easier because the authorities that make up that access level are encapsulated in the “group”, and a single change will affect all of the users.

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:

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:

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

The typical approach to mapping the relationship between “person” and “group” is a many-to-many. In a standard implementation, users have multiple roles, and roles are shared by multiple users. In a group implementation, users have multiple groups, and groups are shared by multiple users. For the same reason we would use a join class between “person” and “authority”, we should use one between “person” and “group”. Please note that when using groups, there should not be a join class between “person” and “authority”, since “group” resides between the two.

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:

The typical approach to mapping the relationship between “group” and “authority” is a many-to-many. In a standard implementation, users have multiple roles, and roles are shared by multiple users. In a group implementation, groups have multiple roles and roles are shared by multiple groups. For the same reason we would use a join class between “person” and “authority”, we should use one between “group” and “authority”.

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:

Optionally, use this class to store request mapping entries in the database instead of defining them with annotations or in application.groovy. This option makes the class configurable at runtime; you can add, remove and edit rules without restarting your application.

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

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

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)

and to reject with the error 500 page, use these (optionally omit rejectPublicInvocations since it defaults to 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:

This is needed when using annotations; if you use the grails.plugin.springsecurity.interceptUrlMap map in application.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:

The analogous interceptUrlMap settings would be:

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

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 SpEL expressions and/or tokens such as IS_AUTHENTICATED_ANONYMOUSLY, IS_AUTHENTICATED_REMEMBERED, and IS_AUTHENTICATED_FULLY. One or more voters (Voters) will process any tokens and enforce a rule based on them:

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

Each approach has its advantages and disadvantages. Annotations and the application.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/application.groovy or in the applicable controllers using annotations.

URLs must be mapped in lowercase if you use the Requestmap or grails-app/conf/application.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.

You can use an @Secured annotation (either the standard org.springframework.security.access.annotation.Secured or the plugin’s grails.plugin.springsecurity.annotation.Secured which has the same attributes and features but also supports defining a closure as the config attribute to make authorization decisions) in your controllers to configure which roles are required for which actions. To use annotations, specify securityConfigType="Annotation", or leave it unspecified because it’s the default:

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:

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:

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

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).

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

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).

To use a static map in application.groovy to secure URLs, first specify securityConfigType="InterceptUrlMap":

Define a Map in application.groovy:

and add any custom mappings as needed, e.g.

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.

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

With this approach you use the Requestmap domain class to store mapping entries in the database. Requestmap has a url property that contains the secured URL pattern and a configAttribute property containing a comma-delimited list of required roles, SpEL expressions, and/or tokens such as IS_AUTHENTICATED_FULLY, IS_AUTHENTICATED_REMEMBERED, and IS_AUTHENTICATED_ANONYMOUSLY.

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

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

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 (/login/impersonate) 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 with one or more roles means the user must have one of the roles and satisty the IS_AUTHENTICATED rule.

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

Spring Security uses the Spring Expression Language (SpEL), which allows you to declare the rules for guarding URLs more descriptively than does the traditional approach, and also allows much more fine-grained rules. Where you traditionally would specify a list of role names and/or special tokens (for example, IS_AUTHENTICATED_FULLY), with Spring Security’s expression support, you can instead use the embedded scripting language to define simple or complex access rules.

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

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

and the corresponding static mappings would be

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 (IP Address Restrictions).

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

The plugin includes GSP tags to support conditional display based on whether the user is authenticated, and/or has the required role to perform a particular action. These tags are in the sec namespace and are implemented in grails.plugin.springsecurity.SecurityTagLib.

grails.plugin.springsecurity.SpringSecurityService provides security utility functions. It is a regular Grails service, so you use dependency injection to inject it into a controller, service, taglib, and so on:

grails.plugin.springsecurity.SpringSecurityUtils is a utility class with static methods that you can call directly without using dependency injection. It is primarily an internal class but can be called from application code.

You can set up event notifications in two ways. The sections that follow describe each approach in more detail.

Enable events with grails.plugin.springsecurity.useSecurityEventListener = true and create one or more Groovy or Java classes, for example:

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

Alternatively, enable events with grails.plugin.springsecurity.useSecurityEventListener = true and register one or more callback closure(s) in grails-app/conf/application.groovy and let SecurityEventListener do the filtering.

Implement the event handlers that you need, for example:

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

To use HTTP Basic Authentication in your application, set the useBasicAuth attribute to true. Also change the basic.realmName default value to one that suits your application, for example:

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 authentication, you can partition the URL patterns and apply Basic authentication to some, but regular form login to others. For example, if you have a web service that uses Basic authentication for /webservice/** URLs, you would configure that using the chainMap config attribute:

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 authentication 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:

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.

Another authentication mechanism supported by Spring Security is certificate-based, or “mutual authentication”. It requires HTTPS, and you must configure the server to require a client certificate (ordinarily only the server provides a certificate). Your username is extracted from the client certificate if it is valid, and you are “pre-authenticated”. As long as a corresponding username exists in the database, your authentication succeeds and you are not asked for a password. Your Authentication contains the authorities associated with your username.

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.

Spring Security supports creating a remember-me cookie so that users are not required to log in with a username and password for each session. This is optional and is usually implemented as a checkbox on the login form; the default auth.gsp supplied by the plugin has this feature.

You are most likely to change these attributes:

The typical pattern of using web site authentication to access restricted pages involves intercepting access requests for secure pages, redirecting to a login page (possibly off-site, for example when using a Single Sign-on implementation such as CAS), and redirecting back to the originally-requested page after a successful login. Each page can also have a login link to allow explicit logins at any time.

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:

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

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

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

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

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

The important aspects of this code are:

If you store mutable data in your custom UserDetails implementation (such as full name in the preceding example), be sure to rebuild the Authentication if it changes. springSecurityService has a reauthenticate method that does this for you:

By default the plugin uses the bcrypt algorithm to hash passwords. You can customize this with the grails.plugin.springsecurity.password.algorithm attribute as described below. In addition you can increase the security of your passwords by adding a salt, which can be a property of the UserDetails instance, a global static value, or any custom value you want.

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:

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

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.

The Spring Security plugin uses hashed passwords and a digest algorithm that you specify. For enhanced protection against dictionary attacks, you should use a salt in addition to digest hashing.

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

Spring Security supports four ways of disabling a user account. When you attempt to log in, the UserDetailsService implementation creates an instance of UserDetails that uses these accessor methods:

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 exception mappings in application.groovy to associate a URL to any or all of these exceptions to determine where to redirect after a failure, for example:

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 application.groovy, for example:

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):

and the form would look something like this:

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:

Specifying a static string in the roleHierarchy property will be sufficient for most applications, but you can also store the information in your database. This is particularly useful if you’re also storing requestmaps in the database. To use persistant storage, run the s2-create-role-hierarchy-entry script. This will create the domain class and enable persistent storage by registering its name as the roleHierarchyEntryClassName setting in grails-app/conf/application.groovy.

For example, running

will generate this class in grails-app/domain/com/yourapp/RoleHierarchyEntry.groovy:

To store the equivalent entries for the ROLE_SUPERADMIN / ROLE_FINANCE_ADMIN / ROLE_ADMIN hierarchy, add code like this to a method in a transactional service:

Remember to update the roleHierarchy beans hierarchy definition by calling SpringSecurityService#reloadDBRoleHierarchy, or your model changes are not reflected in the running application.

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

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:

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

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

To resume as the original user, POST to /logout/impersonate.

You can customize the URLs that are used for this feature, although it is rarely necessary:

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” button is displayed. If not, and the user has the required role, a form is displayed to allow input of the username to switch to:

The default is to use configuration attributes to determine which extra filters to use (for example, Basic Auth, Switch User, etc.) and add these to the “core” filters. For example, setting grails.plugin.springsecurity.useSwitchUserFilter = true adds switchUserProcessingFilter to the filter chain (and in the correct order). The filter chain built here is applied to all URLs. If you need more flexibility, you can use filterChain.chainMap as discussed in chainMap below.

To define custom filters, to remove a core filter from the Spring Security filter chain (not recommended), or to otherwise have control over the Spring Security filter chain, you can specify the filterNames property as a list of strings. As with the default approach, the Spring Security filter chain built here is applied to all URLs.

For example:

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

Use the filterChain.chainMap attribute to define which filters are applied to different URL patterns. You define a Map that specifies one or more lists of filter bean names, each with a corresponding URL pattern.

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:

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.

An alternative to setting the filterNames property is grails.plugin.springsecurity.SpringSecurityUtils.clientRegisterFilter(). This property allows you to add a custom filter to the chain at a specified position. Each standard filter has a corresponding position in the chain (see grails.plugin.springsecurity.SecurityFilterPosition for details). So if you have created an application-specific filter, register it in grails-app/conf/spring/resources.groovy:

Note that in addition to the filter bean, there is also a disabled FilterRegistrationBean registered. This is needed because Spring Boot automatically registers filter beans in the ApplicationContext, so you must register your own FilterRegistrationBean and set its enabled property to false to prevent this.

Then register the filter in grails-app/init/BootStrap.groovy:

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.

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:

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:

A comprehensive list of example spring security apps may be found at:

Returns true if there is an authenticated user.

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

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).

Creates a user and role class (and optionally a requestmap class) in the specified package. If you specify a role-group name with the groupClassName argument, role/group classes will also be generated. If you specify the uiOnly flag, no domain classes are created but the plugin settings are initialized (useful with LDAP, Mock, Shibboleth, etc.)

The general format is:

Creates a persistent token domain class for storing remember-me cookie information in the database. The general format is:

This creates the domain class in the specified package, and also registers the name in grails-app/conf/application.groovy, along with enabling persistent remember-me.

Creates a persistent role hierarchy entry domain class for storing role hierarchy information in the database. The general format is:

This creates the domain class in the specified package, and also registers the name in grails-app/conf/application.groovy, along with enabling persistent role hierarchy storage and lookup.