////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

== Upgrading to 7.x (from Grails 6 / Spring Security 5.x)

This guide covers upgrading the Grails Spring Security plugins from the Grails 6.x era (plugin versions 5.x/6.x, Spring Security 5.8.x) to the Grails 7.x era (plugin version 7.x, Spring Security 6.x).

For the full Grails framework upgrade guide (Java 17 baseline, Groovy 4, coordinate changes, Gradle updates, etc.), see the https://docs.grails.org/7.0.x/guide/upgrading.html[Grails 7 Upgrade Guide].

=== Repository Consolidation

The previously separate Spring Security plugin repositories have been consolidated into a single mono-repository: https://github.com/apache/grails-spring-security[apache/grails-spring-security].
This repository now contains the core plugin and all extension plugins (ACL, CAS, LDAP, OAuth2, REST, and UI).

=== Dependency Changes

All artifacts have moved to the `org.apache.grails` group.
The most notable change is that `spring-security-core` has been renamed to `grails-spring-security` (dropping the `-core` suffix).

Update your `build.gradle` dependencies as follows:

[cols="1,1",options="header"]
|===
| Old Dependency | New Dependency

| `org.grails.plugins:spring-security-core`
| `org.apache.grails:grails-spring-security`

| `org.grails.plugins:spring-security-acl`
| `org.apache.grails:grails-spring-security-acl`

| `org.grails.plugins:spring-security-cas`
| `org.apache.grails:grails-spring-security-cas`

| `org.grails.plugins:spring-security-ldap`
| `org.apache.grails:grails-spring-security-ldap`

| `org.grails.plugins:spring-security-oauth2`
| `org.apache.grails:grails-spring-security-oauth2`

| `org.grails.plugins:spring-security-rest`
| `org.apache.grails:grails-spring-security-rest`

| `org.grails.plugins:spring-security-rest-gorm`
| `org.apache.grails:grails-spring-security-rest-datamapping`

| `org.grails.plugins:spring-security-rest-grailscache`
| `org.apache.grails:grails-spring-security-rest-grails-cache`

| `org.grails.plugins:spring-security-rest-memcached`
| `org.apache.grails:grails-spring-security-rest-memcached`

| `org.grails.plugins:spring-security-rest-redis`
| `org.apache.grails:grails-spring-security-rest-redis`

| `org.grails.plugins:spring-security-ui`
| `org.apache.grails:grails-spring-security-ui`
|===

==== Example

A typical Spring Security Core dependency change:

[source,groovy]
.build.gradle
----
// Before (Grails 6)
implementation 'org.grails.plugins:spring-security-core:6.1.1'

// After (Grails 7)
implementation 'org.apache.grails:grails-spring-security'
----

NOTE: With the unified Grails BOM, versions are managed automatically when using a Grails Gradle plugin.
You no longer need to specify the version explicitly.

=== REST Plugin Token Storage Submodules

If you use the Spring Security REST plugin with a specific token storage backend, note the following renames:

* `spring-security-rest-gorm` is now `grails-spring-security-rest-datamapping` (reflecting the rename of GORM to Grails Data Mapping)
* `spring-security-rest-grailscache` is now `grails-spring-security-rest-grails-cache`
* `spring-security-rest-memcached` is now `grails-spring-security-rest-memcached`
* `spring-security-rest-redis` is now `grails-spring-security-rest-redis`

=== Spring Security 6.x Changes

The underlying Spring Security framework has been upgraded from 5.8.x to 6.x.
Key changes that may affect your application:

* **Jakarta EE namespace**: Spring Security 6 uses `jakarta.servlet` instead of `javax.servlet`. See the https://docs.spring.io/spring-security/reference/migration/index.html[Spring Security Migration Guide] for details.
* **Security filter chain configuration**: The `WebSecurityConfigurerAdapter` has been removed in Spring Security 6. If you have custom security configurations extending this class, you will need to migrate to the component-based approach described in https://spring.io/blog/2022/02/21/spring-security-without-the-websecurityconfigureradapter[Spring Security without the WebSecurityConfigurerAdapter]. The Grails Spring Security plugin handles the core filter chain configuration internally through the `grails.plugin.springsecurity.*` namespace, so for most apps no migration is needed. However, user-defined `@Bean SecurityFilterChain`, `@Bean WebSecurityCustomizer`, `@Bean AuthenticationManager`, and `@Bean UserDetailsManager` beans are not automatically wired into the plugin's filter chain, authentication providers, or user lookup. See the "Coexistence with the component-based Spring Security configuration model" section in the Installation chapter for the full coexistence matrix and the equivalent plugin configuration for each pattern.
* **Default security behaviors**: Some default behaviors have changed in Spring Security 6 (e.g., CSRF protection, session management). Review the https://docs.spring.io/spring-security/reference/migration-7/index.html[Spring Security reference documentation] for the complete list of changes.

=== Automated Migration

The coordinate rename script from the Grails core repository also handles Spring Security artifacts.
Running it will update your Gradle files automatically:

[source,bash]
----
./rename_gradle_artifacts.sh -l my/project/location
----

The script is located in the `etc/bin` directory of the https://github.com/apache/grails-core/tree/7.0.x/etc/bin[grails-core] repository.

=== Configuration Compatibility

The `grails.plugin.springsecurity.*` configuration namespace remains unchanged.
Your existing `application.groovy` or `application.yml` security configuration should work without modification after updating the dependencies.

If you encounter any issues during the upgrade, please file an issue at https://github.com/apache/grails-spring-security/issues[the GitHub repository].
