diff --git a/gradle/docs.gradle b/gradle/docs.gradle index 969c900b9..0cebab466 100644 --- a/gradle/docs.gradle +++ b/gradle/docs.gradle @@ -1,24 +1,24 @@ String versionTxt = project.projectVersion -boolean isSnapshot = versionTxt.endsWith('SNAPSHOT') -boolean isBeta = versionTxt.contains('RC') || versionTxt.contains('M') String stableVersion = '' String snapshotVersion = '' -String[] arr = versionTxt.tokenize('.') -int major = arr[0] as int -int minor = arr[1] as int -int patch -if (isSnapshot || isBeta || arr[2].endsWith("TEST")) { - patch = arr[2].split('-')[0] as int -} else { - patch = arr[2] as int -} - -if (isSnapshot || isBeta) { - stableVersion = "${major}.${minor}.${(patch-1)}".toString() - snapshotVersion = versionTxt -} else { - stableVersion = versionTxt - snapshotVersion = "${major}.${minor}.${patch+1}-SNAPSHOT".toString() +String[] parts = versionTxt.split("\\.") +if (parts.length >= 3) { + int major = parts[0] as int + int minor = parts[1] as int + int patch + if (parts.length > 3) { + patch = parts[2] as int + stableVersion = "$major.$minor.${patch-1}" + snapshotVersion = versionTxt + } else if (parts[2].contains('-')) { + final String[] subparts = parts[2].split("-") + patch = subparts.first() as int + stableVersion = "${major}.${minor}.${patch - 1}" + snapshotVersion = "${major}.${minor}." + subparts[1..-1].join("-") + } else { + stableVersion = versionTxt + snapshotVersion = "$major.$minor.${patch + 1}" + } } def asciidoctorAttributes = [ diff --git a/plugin/src/docs/index.adoc b/plugin/src/docs/index.adoc index 7ebb49624..8578bea21 100644 --- a/plugin/src/docs/index.adoc +++ b/plugin/src/docs/index.adoc @@ -11,6 +11,8 @@ include::{includedir}introduction.adoc[] include::{includedir}whatsNew.adoc[] +include::{includedir}installation.adoc[] + include::{includedir}domainClasses.adoc[] include::{includedir}requestMappings.adoc[] diff --git a/plugin/src/docs/installation.adoc b/plugin/src/docs/installation.adoc new file mode 100644 index 000000000..ea0ce197f --- /dev/null +++ b/plugin/src/docs/installation.adoc @@ -0,0 +1,72 @@ +[[installation]] +== Installation + +=== Prerequisites + +Ensure you have the following set up: + +* A Grails project +* A working internet connection + +==== Installation Steps + +1. Open your Grails project. + +2. Locate your `build.gradle` file in the root directory of your project. + +3. Add the Spring Security Core Plugin dependency to the `dependencies` section in your `build.gradle`: + +[source,groovy] +---- +dependencies { + // ... other dependencies + implementation 'org.grails.plugins:spring-security-core:${stableVersion}' +} +---- + +4. Save the `build.gradle` file. + +5. Open a terminal or command prompt. + +6. Navigate to your project's root directory using the `cd` command. + +7. Run the following Gradle command to update your project's dependencies: + ++ +[source,bash] +---- +./gradlew clean build +---- ++ + +8. The Spring Security Core Plugin 6.0.0 is now installed and integrated into your Grails project. + +9. You can start using the plugin's features and commands in your application. + +10. Run the <> script to generate domain classes and add the initial configuration settings in `application.groovy`: + ++ +[source,bash] +``` +./gradlew runCommand "-Pargs=s2-quickstart com.yourapp User Role" +``` + +=== Verifying Installation + +To verify that the plugin has been successfully installed, you can run a simple test: + +1. In your Grails project, create a new controller or use an existing one. + +2. Add a secure annotation, such as `@Secured(['ROLE_USER'])`, to a method in your controller. + +3. Run your Grails application using the command: + ++ +[source,bash] +---- +./gradlew bootRun +---- ++ + +4. Access the URL associated with the method you secured. If the plugin is correctly installed, it should enforce the security constraint you defined. + diff --git a/plugin/src/docs/introduction.adoc b/plugin/src/docs/introduction.adoc index d83c53f3c..f33ca04eb 100644 --- a/plugin/src/docs/introduction.adoc +++ b/plugin/src/docs/introduction.adoc @@ -5,131 +5,6 @@ The Spring Security plugin simplifies the integration of https://projects.spring This guide documents configuration defaults and describes how to configure and extend the Spring Security plugin for Grails applications. -=== Release History and Acknowledgment -* Please check https://github.com/grails/grails-spring-security-core[GitHub Release Page] for recent release history -* October 16, 2020 -** 4.0.3 -* July 17, 2020 -** 4.0.2 -* July 13, 2020 -** 4.0.1 -* February 27, 2020 -** 4.0.0 -* May 25, 2019 -** 4.0.0.RC2 release -* May 13, 2019 -** 4.0.0.RC1 release -* April 8, 2019 -** 4.0.0.M1 release -* Jul 24, 2018 -** 3.2.3 release -* Jun 24, 2018 -** 3.2.2 release -* Feb 13, 2018 -** 3.2.1 release -* Sep 26, 2017 -** 3.2.0 release -* May 18, 2017 -** 3.2.0.M1 release -* April 22, 2017 -** 3.1.2 release -* May 10, 2016 -** 3.1.1 release -* May 10, 2016 -** 3.1.0 release -* March 21, 2016 -** 3.0.4 release -* January 10, 2016 -** 3.0.3 release -* January 6, 2016 -** 3.0.2 release -* December 31, 2015 -** 3.0.1 release -* December 8, 2015 -** 3.0.0 release -* November 23, 2015 -** 3.0.0.M2 release -* August 14, 2015 -** 3.0.0.M1 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 -** http://jira.grails.org/issues/?jql=project%20%3D%20GPSPRINGSECURITYCORE%20AND%20fixVersion%20%3D%20%22Grails-Spring-Security-Core%202.0%22%20ORDER%20BY%20updated%20DESC%2C%20priority%20DESC%2C%20created%20ASC[JIRA Issues] -* October 3, 2013 -** 2.0-RC1 release -* April 6, 2012 -** 1.2.7.3 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=13100[JIRA Issues] -* February 2, 2012 -** 1.2.7.2 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=13062[JIRA Issues] -* January 18, 2012 -** 1.2.7.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=13051[JIRA Issues] -* December 30, 2011 -** 1.2.7 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=13025[JIRA Issues] -* December 2, 2011 -** 1.2.6 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=13024[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 -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=12907[JIRA Issues] -* August 17, 2011 -** 1.2.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=12811[JIRA Issues] -* July 31, 2011 -** 1.2 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=12503[JIRA Issues] -* May 23, 2011 -** 1.1.3 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=12502[JIRA Issues] -* February 26, 2011 -** 1.1.2 release -* February 26, 2011 -** 1.1.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11909[JIRA Issues] -* August 8, 2010 -** 1.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11908[JIRA Issues] -* August 1, 2010 -** 1.0.1 release -* July 27, 2010 -** 1.0 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11907[JIRA Issues] -* July 16, 2010 -** 0.4.2 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11906[JIRA Issues] -* June 29, 2010 -** 0.4.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11905[JIRA Issues] -* June 21, 2010 -** 0.4 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11904[JIRA Issues] -* May 12, 2010 -** 0.3.1 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11903[JIRA Issues] -* May 12, 2010 -** 0.3 release -** http://jira.grails.org/secure/ReleaseNote.jspa?projectId=10229&version=11902[JIRA Issues] -* May 2, 2010 -** 0.2 release -* April 27, 2010 -** initial 0.1 release - -This plugin is based on work done for the https://grails.org/plugin/acegi/[Acegi] plugin by Tsuyoshi Yamamoto. - include::introduction/configGroovy.adoc[] include::introduction/gettingStarted.adoc[] diff --git a/plugin/src/docs/newInV2.adoc b/plugin/src/docs/newInV2.adoc deleted file mode 100644 index 67eb6cd71..000000000 --- a/plugin/src/docs/newInV2.adoc +++ /dev/null @@ -1,179 +0,0 @@ -[[newInV2]] -== What's New in Version 2.0 - -There are many changes in the 2.x versions of the plugin from the older approaches in 1.x. - -=== 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 in <>. - -==== Logout POST only - -By default only POST requests are allowed to trigger a logout. To allow GET access, add this - -[source,groovy] ----- -grails.plugin.springsecurity.logout.postOnly = false ----- - -==== bcrypt by default - -The default password hashing algorithm is now https://en.wikipedia.org/wiki/Bcrypt[bcrypt] since it is a very robust hashing approach. https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] is similar and is also supported. You can still use any message digest algorithm that is supported in your JDK; see https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html[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: - -[source,groovy] ----- -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 - -[source,groovy] ----- -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. - -[source,groovy] ----- -@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: - -[source,groovy] ----- -@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: - -[source,groovy] ----- -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 {apidocs}org/springframework/security/core/context/SecurityContextHolderStrategy.html[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 `grails-app/conf/application.yml` - -[source,groovy] ----- -environments: - development: - grails: - logging: - jul: - usebridge: true - plugin: - springsecurity: - debug: - useFilter: true - production: - grails: - logging: - jul: - usebridge: true ----- - -Also add the implementation class name in your logback configuration: - -[source,groovy] -.grails-app/conf/logback.groovy ----- -logger 'grails.plugin.springsecurity.web.filter.DebugFilter', INFO, ['STDOUT'], false ----- - -=== 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 https://burtbeckwith.com/blog/?p=1398[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 {apidocs}org/springframework/security/authentication/AuthenticationDetailsSource.html[AuthenticationDetailsSource] interface, e.g.: - -[source,groovy] -.`MyAuthenticationDetailsSource.groovy` ----- -package com.mycompany - -import javax.servlet.http.HttpServletRequest - -import org.springframework.security.authentication.AuthenticationDetailsSource - -class MyAuthenticationDetailsSource implements AuthenticationDetailsSource { - - MyWebAuthenticationDetails buildDetails(HttpServletRequest context) { - // build a MyWebAuthenticationDetails - } -} ----- - -and registering that as the `authenticationDetailsSource` bean in `resources.groovy` - -[source,groovy] -.`resources.groovy` ----- -import com.mycompany.MyAuthenticationDetailsSource - -beans = { - authenticationDetailsSource(MyAuthenticationDetailsSource) { - // any required properties - } -} ----- diff --git a/plugin/src/docs/newInV3.adoc b/plugin/src/docs/newInV3.adoc deleted file mode 100644 index 1d3a4d22e..000000000 --- a/plugin/src/docs/newInV3.adoc +++ /dev/null @@ -1,80 +0,0 @@ -[[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/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/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 <>), `ipRestrictions` (see <>), `filterChain.chainMap` (see <>), `secureChannel.definition` (see <>), 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 { - ... - implementation '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 <> 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. diff --git a/plugin/src/docs/newInV321.adoc b/plugin/src/docs/newInV321.adoc deleted file mode 100644 index 9e4a987b3..000000000 --- a/plugin/src/docs/newInV321.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[newInV321]] -== What's New in Version 3.2.1 - -=== Default SecurityContextHolder strategy - -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. - -[WARNING] -==== -Beware when using thread pools. Threads keep the security context they inherit when the thread is created the first time. The context isn't updated when the thread is reused for a different task. -==== \ No newline at end of file diff --git a/plugin/src/docs/newInV4.adoc b/plugin/src/docs/newInV4.adoc deleted file mode 100644 index b0969b9d2..000000000 --- a/plugin/src/docs/newInV4.adoc +++ /dev/null @@ -1,82 +0,0 @@ -[[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 { - ... - implementation '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 <> 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. diff --git a/plugin/src/docs/newInV401.adoc b/plugin/src/docs/newInV401.adoc deleted file mode 100644 index 6f1b8a8c9..000000000 --- a/plugin/src/docs/newInV401.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[newInV401]] -== What's New in Version 4.0.1 - -=== Default SecurityContextHolder strategy - -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. diff --git a/plugin/src/docs/newInV5.adoc b/plugin/src/docs/newInV5.adoc deleted file mode 100644 index ca0ab428e..000000000 --- a/plugin/src/docs/newInV5.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[newInV5]] -== What's New in Version 5.0.0 - -Version 5.x of the plugin requires Grails 5 or later; this version also updates to Spring Security Core version 5.6.1. We recommend you to check more details about what's new in Spring Security 5.6 at https://docs.spring.io/spring-security/reference/whats-new.html. - - diff --git a/plugin/src/docs/thenewselectoption.png b/plugin/src/docs/thenewselectoption.png new file mode 100644 index 000000000..cd6049059 Binary files /dev/null and b/plugin/src/docs/thenewselectoption.png differ diff --git a/plugin/src/docs/whatsNew.adoc b/plugin/src/docs/whatsNew.adoc index 76e72818f..af2139ec6 100644 --- a/plugin/src/docs/whatsNew.adoc +++ b/plugin/src/docs/whatsNew.adoc @@ -1,14 +1,30 @@ [[whatsNew]] -== What's New +== What's New in Grails Spring Security Core Plugin 6.0.0 -include::newInV5.adoc[leveloffset=1] +This release is more than just an upgrade; it's a transformative step towards elevating your application's security, compatibility, and development experience. Get ready to embark on a journey of enhancements that will empower you to build robust, modern web applications. Let's dive into the exciting changes that version 6.0.0 brings. -include::newInV401.adoc[leveloffset=1] +==== Elevated Security and Compatibility -include::newInV4.adoc[leveloffset=1] +Version 6.0.0 of the Grails Spring Security Core Plugin brings enhanced security features and improved compatibility with Grails 6. With a revamped underlying Spring Security framework powered by version 5.8.6, your application gains access to the latest security enhancements and bug fixes, safeguarding it against evolving threats and vulnerabilities. -include::newInV321.adoc[leveloffset=1] +==== Streamlined Commands for Grails 6 -include::newInV3.adoc[leveloffset=1] +One of the notable improvements is the seamless transition to Grails 6. The plugin now offers upgraded commands that are fully compatible with Grails 6. This is a vital enhancement as it ensures your existing scripts remain functional without compatibility issues. The familiar commands like `s2-quickstart` have been refined, enabling you to trigger them using Gradle tasks. For example, you can now execute: + +[source,shell] +---- +./gradlew runCommand "-Pargs=s2-quickstart com.yourapp User Role" +---- + +This aligns perfectly with Grails 6's development landscape, making your application's migration smoother than ever before. + +==== Effortless Documentation Navigation + +We understand the importance of hassle-free documentation navigation. With the Internal Docs task now enhanced, generating documentation becomes a breeze. But that's not all – we've introduced a slick select drop-down feature. This feature allows you to effortlessly switch between documentation for different releases. Whether you're exploring the latest version or revisiting older ones, finding the information you need has never been easier. + +image::https://grails.org/blog/2023-08-25-thenewselectoption.png[Documentation Select Option] + +==== Embracing the Grails 6 Framework + +In the ever-evolving world of web development, the Grails Spring Security Core Plugin is keeping pace. Version 6.0.0 ensures seamless integration with Grails 6, enabling you to harness the cutting-edge features and improvements of the Grails framework. This integration ensures that your application can leverage both the power of Grails and the robust security features of the plugin. -include::newInV2.adoc[leveloffset=1] \ No newline at end of file