plugin/src/docs/newInV4.adoc

[[newInV4]]
== What's New in Version 4.0

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

In general, using the Spring Security plugin in Grails 4 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 5 (currently 5.1.13.RELEASE), but the changes required were primarily internal and don't affect usage. There are new features in Spring Security 5 however, and the plugin will be updated in future releases to take advantage of those.

Spring Security 5 changed the way passwords are encoded and compared for matches. Formerly a salt was passed into the encoder when calling encode for the password.
To upgrade, you must migrate your password database data first to look like so by putting the salt in curly brackets before the password:

    {bcrypt}someencryptedpassword   // using bcrypt
    {noop}plaintextpassword         // using plain text

This allows Spring Security to automatically figure out which algorithm class to use with DelegatingPasswordEncoder https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/crypto/password/DelegatingPasswordEncoder.html.

Refer to the links below for more information on upgrading:

* https://www.baeldung.com/spring-security-5-password-storage
* https://dzone.com/articles/password-encoder-migration-with-spring-security-5

If you don't migrate your password data, you will see exceptions like "There is no PasswordEncoder mapped for the id “null”". Keep in mind you might have to fix tests as well that aren't encoding passwords.

[WARNING]
====
There are a few breaking changes. Anywhere you use the passwordEncoder bean it has new parameter to initialize it. The same is password matching, the new method is now `matches(CharSequence rawPassword, String prefixEncodedPassword)`.
See `SpringSecurityCoreGrailsPlugin.groovy` for more information on initializing the bean if you need to override it.
====


=== Installation

==== Grails 4.0.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 4.0.x is only compatible with Grails 4.0.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.