Spring Security UI Plugin - Reference Documentation

Add an entry in the dependencies block of your build.gradle file, changing the version as needed:

For previous Grails 3 versions ( 3.0.x, 3.1.x and 3.2.x ) use:

Also be sure to update the versions when new releases are available.

The default action for the User controller is search. By default only the standard fields (username, enabled, accountExpired, accountLocked, and passwordExpired) are available but this is customizable with the s2ui-override script - see the Customization section for details.

You can search by any combination of fields, and the username field has an Ajax autocomplete to assist in finding instances. In this screenshot you can see that an email field has been added to the domain class and UI. Leave all fields empty and all checkboxes set at "Either" to return all instances.

This example shows a search for usernames containing 'adm' (the search is case-insensitive and the search string can appear anywhere in the username). Results are shown paginated in groups of 10. All of the column headers are clickable and will sort the results by that field.

After clicking through to the 'admin' User you get to the edit page (there are no view pages):

You can update any of the attributes or delete the User. You can see that there’s a "Login as user" button here - that is only shown if you’re authenticated with a User who is granted ROLE_SWITCH_USER (this role name can be configured in application.groovy):

This allows you to temporarily assume the identity of another User (see the Spring Security Core plugin documentation for more information about switch-user). The "Logged in as …​" information in the top right of the screen will change to show that you’re running as another User and provide a link to switch back. The role name ROLE_SWITCH_USER is the default but you can change the value with the grails.plugin.springsecurity.ui.switchUserRoleName setting in application.groovy.

If you click the Roles tab you can see the roles granted to this User and can click through to its edit page:

You can create new Users by going to /user/create or by clicking the Create action in the Users menu.

The default action for the Role controller is search. By default only the authority field is available but this is customizable with the s2ui-override script - see the Customization section for details.

The authority field has an Ajax autocomplete to assist in finding instances. Leave the field empty to return all instances.

Search is case-insensitive and the search string can appear anywhere in the name (and you can omit the ROLE_ prefix). Results are shown paginated in groups of 10 but if there’s only one result you’ll be forwarded to the edit page for that Role. The authority column header is clickable and will sort the results by that field.

After clicking through to a Role you get to the edit page (there are no view pages):

You can update any of the attributes or delete the Role. Any user that had been granted the Role will lose the grant but otherwise be unaffected.

If you click the Users tab you can see which users have a grant for this Role and can click through to their edit page:

You can create new Roles by going to /role/create or by clicking the Create action in the Roles menu.

The default action for the Requestmap controller is search. By default only the standard fields (url and configAttribute) are available but this is customizable with the s2ui-override script - see the Customization section for details.

You can search by any combination of fields, and the url and configAttribute fields have an Ajax autocomplete to assist in finding instances. Leave both fields empty to return all instances.

Searching is case-insensitive and the search string can appear anywhere in the field. Results are shown paginated in groups of 10 and you can click on either header to sort by that field:

After clicking through to a Requestmap you get to the edit page (there are no view pages):

You can update any of the attributes or delete the Requestmap. Editing or deleting a Requestmap resets the cache of loaded instances, so your changes will take effect immediately.

You can create new Requestmaps by going to /requestmap/create or by clicking the Create action in the Requestmaps menu.

Creating a Requestmap resets the cache of loaded instances, so your changes will take effect immediately.

Navigate to /register/:

By default e-mail validation for user creation is turned on. If you wish to turn it off see the 'E-Mail Validation Parameter' section below. If this is turned off then no e-mail is sent to the user and they are automatically redirected to the link that would have been sent in the e-mail.

After filling out valid values an email will be sent and you’ll see a success screen:

Click on the link in the email:

and you’ll finalize the process, which involves enabling the locked user and pre-authenticating, then redirecting to the configured destination:

The post-registration destination url is configurable in grails-app/conf/application.groovy using the postRegisterUrl attribute:

If you don’t specify a value then the grails.plugin.springsecurity.successHandler.defaultTargetUrl value will be used, which is '/' by default.

In addition, each new user will be granted ROLE_USER after finalizing the registration. If you want to change the default role, add more, or grant no roles at all (for example if you want an admin to approve new users and explicitly enable new users) then you can customize that with the defaultRoleNames attribute (which is a List of Strings):

By default the plugin uses the Mail plugin to send emails, but only if it is installed. This is configurable by registering your own MailStrategy implementation - see the section on Configuration for more information. The plugin assumes that the Mail plugin and an SMTP server are already configured.

You can customize the subject, body, and from address of the registration email by overriding the default values in grails-app/conf/application.groovy, for example:

The emailBody property should be a GString and will have the User domain class instance in scope in the user variable, and the generated url to click to finalize the signup in the url variable.

or

You should consider the registration code as starter code - every signup workflow will be different, and this should help you get going but is unlikely to be sufficient. You may wish to collect more information than just username and email - first and last name for example. Run grails s2ui-override register to copy the registration controller and GSPs into your application to be customized.

If there are unexpected validation errors during registration (which can happen when there is a disconnect between the domain classes and the code in RegisterController they will be logged at the warn or error level, so enable logging to ensure that you see the messages, e.g.

The plugin uses its grails.plugin.springsecurity.ui.RegistrationCode domain class to store a token associated with the new users' username for use when finishing the registration process after the user clicks the link in the generated email (and also as part of the forgot-password workflow). The plugin includes a controller and GSPs to manage these instances.

The default action for the RegistrationCode controller is search. By default only the standard fields (username and token) are available but this is customizable with the s2ui-override script - see the Customization section for details.

You can search by any combination of fields, and both fields have an Ajax autocomplete to assist in finding instances. Leave both fields empty to return all instances.

Searching is case-insensitive and the search string can appear anywhere in the field. Results are shown paginated in groups of 10 and you can click on any header to sort by that field:

After clicking through to a RegistrationCode you get to the edit page (there are no view pages):

You can update the username or token attribute or delete the RegistrationCode.

Since instances are created during the "User Registration" and "Forgot Password" workflows, there is no functionality in this plugin to create new instances.

Navigate to /register/forgotPassword:

The default is to have e-mail validation for forgetting a password. This is now configurable which will be explained below.

After entering a valid username an email will be sent and you’ll see a success screen:

Click on the link in the email:

and you’ll open the reset password form:

After entering a valid password you’ll finalize the process, which involves storing the new password hashed in the user table and pre-authenticating, then redirecting to the configured destination:

The post-reset destination url is configurable in grails-app/conf/application.groovy using the postResetUrl attribute:

If you don’t specify a value then the defaultTargetUrl value will be used, which is '/' by default.

You can customize if you want to have the user get e-mails for validation before they can reset their password. To turn off e-mail validation set the parameter requireForgotPassEmailValidation to false. If not set it will default to true. This can be set in grails-app/conf/application.groovy or grails-app/conf/application.yml under

If e-mail validation is turned off, it is recommended to use the forgotPasswordExtraValidation below.

It is recommended the provided script named s2ui-create-challenge-questions be used to generate challenge questions.

All the answers will be encrypted and it will use the same encryption settings as the what is used to store the password for each user. The service to handle this listener is automatically created and configured when you use the plugin.

The option to add challenge questions can be turned on will work independent of e-mail validation. If the e-mail validation is turned on this step will occur before the e-mail is sent out.

To make this work, the domain object must have a link to your User Object. This is done by setting the validationUserLookUpProperty which defaults to 'user'.

This can be customized in either grails-app/conf/application.groovy or grails-app/conf/application.yml

Each list item in the forgotPasswordExtraValidation has three options, though each should only have two. If you have both labelDomain and labelMessage then labelDomain will be used as it takes precedences.

This can be customized in either grails-app/conf/application.groovy or grails-app/conf/application.yml

If the above is configured you will see a menu item to List and Create Challenge questions for each user.

To use the challenge questions functionality please set the domain class which will hold the answers with the forgotPasswordExtraValidationDomainClassName property. This is Domain object that contains any reference that is needed by prop (question) and labelDomain (answer).

By default the plugin uses the Mail plugin to send emails, but only if it is installed. This is configurable by registering your own MailStrategy implementation - see the section on Configuration for more information. The plugin assumes that the Mail plugin and an SMTP server are already configured.

You can customize the subject, body, and from address of the reset email by overriding the default values in grails-app/conf/application.groovy, for example:

The emailBody property should be a GString and will have the User domain class instance in scope in the user variable, and the generated url to click to reset the password in the url variable.

Like the registration code, consider this workflow as starter code. Run grails s2ui-override register to copy the registration controller and GSPs into your application to be customized.

The default action for the AclClass controller is search. By default only the standard fields are available but this is customizable with the s2ui-override script - see the Customization section for details.

The className field has an Ajax autocomplete to assist in finding instances. Leave the field empty to return all instances.

Searching is case-insensitive and the search string can appear anywhere in the field. Results are shown paginated in groups of 10 and you can click on the className column header to sort the results by that field:

The default action for the AclSid controller is search. By default only the standard fields are available but this is customizable with the s2ui-override script - see the Customization section for details.

The sid field has an Ajax autocomplete to assist in finding instances. Leave the field empty and principal set to Either to return all instances.

Results are shown paginated in groups of 10. The column headers are clickable and will sort the results by that field:

The default action for the AclObjectIdentity controller is search. By default only the standard fields are available but this is customizable with the s2ui-override script - see the Customization section for details.

Leave all fields at their default values to return all instances.

Results are shown paginated in groups of 10 and you can click on any header to sort by that field:

The default action for the AclEntry controller is search. By default only the standard fields are available but this is customizable with the s2ui-override script - see the Customization section for details.

Leave all fields at their default values to return all instances.

Results are shown paginated in groups of 10 and you can click on any header to sort by that field:

The default action for the PersistentLogin controller is search. By default only the standard fields (username, token, and series) are available but this is customizable with the s2ui-override script - see the Customization section for details.

You can search by any combination of fields, and all fields have an Ajax autocomplete to assist in finding instances. Leave all fields empty to return all instances.

Searching is case-insensitive and the search string can appear anywhere in the field. Results are shown paginated in groups of 10 and you can click on any header to sort by that field:

After clicking through to an instance you get to the edit page (there are no view pages):

You can update the token or lastUsed attribute or delete the instance.

Since instances are created during authentication by the spring-security-core plugin, there is no functionality in this plugin to create new instances.

The Security Configuration menu item displays all security-related attributes in application.groovy. The names omit the grails.plugin.springsecurity prefix:

The Mappings menu item displays the current request mapping mode (Annotation, Requestmap, or Static) and all current mappings:

The Current Authentication menu item displays your Authentication information, mostly for reference to see what a typical one contains:

The User Cache menu item displays information about cached users if the feature is enabled (it is disabled by default).

The Filter Chains menu item displays your configured Filter chains. It is possible to have multiple URL patterns each with its own filter chain, for example when using HTTP Basic Auth for a web service. By default since the 3.0.0 release the spring-security-core s2-quickstart script configures empty filter chains for static assets to avoid unnecessary security checks (although of course if you need to secure some or all of your static assets you should reconfigure these).

The Logout Handlers menu item displays your registered LogoutHandlers. Typically there will be just the ones shown here, but you can register your own custom implementations, or a plugin might contribute more:

The Voters menu item displays your registered AccessDecisionVoters. Typically there will be just the ones shown here, but you can register your own custom implementations, or a plugin might contribute more:

The Authentication Providers menu item displays your registered AuthenticationProviders. Typically there will be just the ones shown here, but you can register your own custom implementations, or a plugin (e.g. LDAP) might contribute more:

The Secure Channel Definition menu item displays your registered channel security mappings.

The plugin’s controllers and GSPs are easily overridden using the s2ui-override script. The general syntax for running the script is

The script will copy an empty controller that extends the corresponding plugin controller into your application so you can override individual actions and methods as needed. It also copies the controller’s GSPs. The exceptions are 'auth' and 'layout' which only copy GSPs.

For auth and layout, you do not supply a package name.

For example:

For the other types aclclass, aclentry, aclobjectidentity, aclsid, persistentlogin,register, registrationcode, requestmap, role, securityinfo, user, you supply a package name as command parameter. That it is to say:

The files copied for each type are summarized here:

All of the plugin’s displayed strings are localized and stored in the plugin’s grails-app/i18n/messages.spring-security-ui.properties file. You can override any of these values by putting an override in your application’s grails-app/i18n/messages.properties file.

There are a few configuration options specified in DefaultUiSecurityConfig.groovy that can be overridden in your application’s grails-app/conf/application.groovy

The plugin uses the Asset Pipeline plugin to manage its resources. This makes it very easy to provide your own version of some or all of the static resources since asset-pipeline will always use a file in the application’s assets directory instead of a plugin’s if it exists.

Instead of depending on either the jQuery or jQuery UI plugins, this plugin includes its own copy of jquery.js, jquery-ui.js, and jquery-ui.css. Note that the versions are not hard-coded, but instead they take advantage of the feature in asset-pipeline where you can embed Groovy code in a file to specify the name and path.

The layouts use grails-app/assets/javascripts/jquery.js, which contains this:

This resolves to grails-app/assets/javascripts/jquery/jquery-2.1.4.js, and to use your own version, either use the same approach in a file called jquery.js or rename your file to jquery.js.

Likewise for jQuery UI, the JavaScript file is grails-app/assets/javascripts/jquery-ui.js, which contains this

and the CSS file grails-app/assets/stylesheets/jquery-ui.css, which contains

The JavaScript file resolves to grails-app/assets/javascripts/jquery-ui/jquery-ui-1.10.3.custom.js, and to use your own version, either use the same approach in a file called jquery-ui.js or rename your file to jquery-ui.js.

The CSS file resolves to grails-app/assets/stylesheets/smoothness/jquery-ui-1.10.3.custom.css, and to use your own version, either use the same approach in a file called jquery-ui.js or rename your file to jquery-ui.js.

Use your own jquery-ui.js and/or jquery-ui.css to override the plugin’s.

The springSecurityUI.gsp layout includes grails-app/assets/stylesheets/spring-security-ui.css, which has no style declarations and only includes other CSS files:

and grails-app/assets/javascripts/spring-security-ui.js which has no JavaScript code and only includes other JavaScript files:

The register.gsp layout layout includes grails-app/assets/stylesheets/spring-security-ui-register.css, which has no style declarations and only includes other CSS files:

and grails-app/assets/javascripts/spring-security-ui-register.js which has no JavaScript code and only includes other JavaScript files:

The remaining JavaScript files are

and the remaining CSS files are

In recent versions of the Spring Security Core plugin, the “User” domain class is generated by the s2-quickstart script with code to automatically hash the password. This makes the code simpler (for example in controllers where you create users or update user passwords) but older generated classes don’t have this generated code. This presents a problem for plugins like this one since it’s not possible to reliably determine if the domain class hashes the password or if you use the older approach of explicitly calling springSecurityService.encodePassword().

The unfortunate consequence of mixing a newer domain class that does password hashing with controllers that call springSecurityService.encodePassword() is the the passwords get double-hashed, and users aren’t able to login. So to get around this there’s a configuration option you can set to tell this plugin’s controllers whether to hash or not: grails.plugin.springsecurity.ui.encodePassword.

This option defaults to false, so if you have an older domain class that doesn’t handle hashing just enable this plugin’s hashing:

h4. Strategy classes

The plugin’s SpringSecurityUiService implements several “strategy” interfaces to make it possible to override its functionality in a more fine-grained way.

These are defined by interfaces in the grails.plugin.springsecurity.ui.strategy package:

The controllers, taglib, and even the service never call strategy methods directly on the service, only via a strategy interface.

Each interface has a default implementation, e.g. DefaultAclStrategy, DefaultErrorsStrategy, etc., and these simply delegate to SpringSecurityUiService (except for MailStrategy, which has MailPluginMailStrategy as its default implementation which uses the Mail plugin to send emails). Each of the default implementations is registered as a Spring bean:

To override the functionality defined in one of the strategy interfaces, register your own implementation of the interface in your application’s grails-app/conf/spring/resources.groovy, e.g.

and yours will be used instead.

By default the registration controller has rather strict requirements for valid passwords; they must be between 8 and 64 characters and must include at least one uppercase letter, at least one number, and at least one symbol from “!@#$%^&”. You can customize these rules with these application.groovy attributes:

Generates controllers that extend the plugin’s controllers and copies their GSPs to your application for overriding of functionality.

The general format is:

The script will copy an empty controller that extends the corresponding plugin controller into your application so you can override individual actions and methods as needed. It also copies the controller’s GSPs. The exceptions are when type is 'auth' or 'layout' which only copy GSPs.

See the Customization section for more details.

Generates controllers, services, domain object, views, i18N, and application configuration to have challenge questions

The general format is:

This script will create one Domain Class. This will contain a link to the user and also contain one entry for each questions and answer. If you pass in either no package or the same package as the what is used for the Challenge Question domain it will not put a package in front of the User class. However, if you pass in a different package then it will add the package in front of the user class.

This script will create one controller which contains all the logic for handling the actions needed to provide a user interface to manage different users challenge questions and answers.

This script will create two services. The first service is to handle to be the implementation for the controller/domain object handling the data needed to set/get questions and answers. The second service is a listener service which ensures that anytime an answer is created or updated the value is encypted before it is stores in the database.

This script will create three views. Each of the three views (List/index, edit, and create) will support all the CRUD operations.

This script will add lines into your application.groovy file in order to ensure the questions and answers are properly configured.

This script will insert one line into messages.properties. This will be the menu item in the nav bar for spring security.