plugin/src/docs/newInV3.adoc

[[newInV3]]
== What's New in Version 3.0

Version 3.x of the plugin requires Grails 3 or higher; to use the plugin in Grails 2 applications use the latest 2.x.x version of the plugin.

In general, using the Spring Security plugin in Grails 3 is nearly identical to using it in Grails 2, other than obvious differences under the hood such as no longer using `web.xml`. The configuration settings are the same, and the processes for customizing how things work (changing settings, overriding and customizing Spring beans, etc.) are generally the same. There were no package or configuration name changes, so customizations and extensions should continue to work. The plugin now uses Spring Security 4 (currently 4.0.3.RELEASE), but the changes required were primarily internal and don't affect usage. There are new features in Spring Security 4 however, and the plugin will be updated in future releases to take advantage of those.

Spring Security 4 changed the default URLs and parameter names for login, logout, switch-user, etc. This is handled by the plugin for you and is usually transparent, but you should be aware of the changes if you want to customize the filters or GSPs:

* `/j_spring_security_check` (the `apf.filterProcessesUrl` config setting) changed to `/login/authenticate`
* `/j_username` (the `apf.usernameParameter` and `switchUser.usernameParameter` config settings) changed to `username`
* `/j_password` (the `apf.passwordParameter` config setting) changed to `password`
* `/j_spring_security_logout` (the `logout.filterProcessesUrl` config setting) changed to `/logoff`
** In Spring Security 4 the value is actually `/logout`, but that conflicts with the standard `LogoutController` url, so the plugin uses `/logoff` instead
* `_spring_security_remember_me` (the `rememberMe.parameter` config setting) changed to `remember-me`
* `/j_spring_security_switch_user` (the `switchUser.switchUserUrl` config setting) changed to `/login/impersonate`
* `/j_spring_security_exit_user` (the `switchUser.exitUserUrl` config setting) changed to `/logout/impersonate`

Note that the 2.x.x plugin was written primarily in Java, with Groovy used only for dynamic calls, but in version 3 all Java classes were converted to Groovy with the `@CompileStatic` annotation. Java was used because Spring Security is configured as a chain of servlet filters that fire for every request (including static resources) and the cumulative cost of many small Groovy performance hits can be non-trivial. But with `@CompileStatic` we get the best of both worlds - Java performance, and Groovy compactness. If you're curious you can see these changes https://github.com/grails-plugins/grails-spring-security-core/commit/da06fa44d8bbea0ff374dd31b1c6b28426bdf7b4[in this GitHub commit].

Also, since Grails 3 no longer supports Gant scripts, the plugin's scripts were converted to the newer approach. This should have no effect on usage as the calling syntax and results are the same as before, although the console output looks somewhat different. You can see these changes https://github.com/grails-plugins/grails-spring-security-core/commit/16484f44fe25a6f1c8687b8e27db6f08ed871436[in this GitHub commit].

[WARNING]
====
There are a few breaking configuration changes as of version 3.0.0.M2. Prior to that version, some configuration properties were specified as a `Map` where the keys and values were both data. This caused various problems, primarily due to period characters in map keys. There are now no configuration properties that are single maps; all have been converted to lists of single-entry maps. This includes `controllerAnnotations.staticRules` and `interceptUrlMap` (see <<requestMappings>>), `ipRestrictions` (see <<ip>>), `filterChain.chainMap` (see <<filters>>), `secureChannel.definition` (see <<channelSecurity>>), and `failureHandler.exceptionMappings`.
====

=== Installation

==== Grails 3.3.x

The "`installation`" process has changed in version 3+ of the plugin, but they're the same as for any Grails 3 plugin. Simply add an entry in the `dependencies` block of your `build.gradle` file, changing the version as needed:

[source,groovy]
[subs="attributes"]
.`build.gradle`
----
dependencies {
   ...
   compile 'org.grails.plugins:spring-security-core:{stableversion}'
   ...
----

NOTE: Version 3.2.x is only compatible with Grails 3.3.x or higher.

Snapshots are published automatically to https://oss.jfrog.org/[Artifactory OSS] on every successful build. To use them:

[source,groovy]
[subs="attributes"]
.`build.gradle`
----
repositories {
  ...
  maven { url "https://oss.jfrog.org/artifactory/oss-snapshot-local" }
}
dependencies {
   ...
   compile 'org.grails.plugins:spring-security-core:{snapshotversion}'
   ...
----

==== Grails 3.0.x, 3.1.x, 3.2.x

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

[source,groovy]
[subs="attributes"]
.`build.gradle`
----
dependencies {
   ...
   compile 'org.grails.plugins:spring-security-core:3.1.2'
   ...
----

Run the <<s2-quickstart>> script to generate domain classes and add the initial configuration settings in `application.groovy`.

=== Configuration

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.