Major release 4 (#1924)

* refactor(token-client): modernize HTTP client to Apache HttpClient 5

Migrate DefaultHttpClientFactory from Apache HttpClient 4 to 5 with
modern builder patterns and improved connection pooling.

Key changes:
- Replace manual socket factory registry with PoolingHttpClientConnectionManagerBuilder
- Use DefaultClientTlsStrategy instead of deprecated SSLConnectionSocketFactoryBuilder
- Add ConnectionConfig for better timeout management
- Fix connection pool caching: restore computeIfAbsent() to properly reuse
  connection pools per client ID (was incorrectly using compute() which
  recreated pools on every request)
- Explicitly configure TLS 1.2 and 1.3 support
- Remove redundant setSSLContext() and setSSLSocketFactory() calls as
  SSL configuration is now embedded in the connection manager

This resolves the "Connection pool shut down" issue by ensuring each
client identity maintains its own isolated and reusable connection pool.

Fixes: Connection pool shutdown errors reported in production
Related: commit 5b77378 (May 2022 fix), commit 92d1888 (Jan 2024 regression)

* refactor: prepare Major Release 4 - Jakarta EE and Spring Boot 4 upgrade

Major dependency upgrades for release 4.0:

1. Jakarta EE Migration
   - Replace javax.annotation.* with jakarta.annotation.* across all modules
   - Aligns with Jakarta EE specification for Java EE namespace migration

2. Spring Framework Upgrades
   - Spring Boot: 3.5.9 → 4.0.3
   - Spring Framework: 6.2.15 → 7.0.5
   - Spring Security: 6.5.7 → 7.0.3
   - Spring Security OAuth2: 6.5.7 → 7.0.3

3. Test Framework Upgrades
   - JUnit Jupiter: 5.12.2 → 6.0.3
   - Maven Surefire: 3.5.4 → 3.5.5

Affected modules:
- java-api, env, java-security, java-security-test
- spring-security, spring-security-compatibility, spring-security-legacy-module
- token-client
- All sample applications

No functional changes, purely dependency version updates and namespace
migration for Jakarta EE compatibility.

* refactor: update module list - add spring-security-legacy-module, remove deprecated spring-xsuaa modules

* chore: bump version to 4.0.0 for Major Release 4

Update all module versions from 3.6.x to 4.0.0 to reflect the major
release with breaking changes:

- Jakarta EE migration (javax → jakarta)
- Spring Boot 4.0 and Spring Framework 7.0 upgrade
- JUnit Jupiter 6.0 upgrade
- HTTP Client 5 migration

All modules updated:
- Parent pom
- Core modules (java-api, env, java-security, token-client)
- Spring modules (spring-security, spring-security-compatibility, spring-security-legacy-module)
- Test modules (java-security-test)
- All sample applications
- BOM module

* fix: update spring-security-compatibility to use spring-security-legacy-module

Replace dependency on deprecated spring-xsuaa artifact with the renamed
spring-security-legacy-module artifact.

* fix: migrate spring-security-legacy-module to HTTP Client 5

Update dependency from httpclient 4 to httpclient5 to match the
HTTP Client 5 migration in the rest of the codebase.

* fix: update HTTP Client 5 imports in spring-security-legacy-module

Update imports from org.apache.http to org.apache.hc.client5 to match
the HTTP Client 5 migration.

Files updated:
- XsuaaTokenFlowAutoConfiguration.java
- JwtDecoderBuilder.java

* fix: remove spring-xsuaa-test dependency from token-client and bom

Remove test dependency on spring-xsuaa-test module which was deleted
in Major Release 4.

* fix: Resolve build failures after spring-xsuaa module removal

This commit fixes all compilation and build issues that arose from
removing the deprecated spring-xsuaa module.

Changes:
- Remove spring-xsuaa test dependency from java-security/pom.xml
- Delete outdated SpringSecurityContextTest from java-security
  (equivalent test exists in spring-security-legacy-module)

- Update HTTP Client 4 to 5 imports in test files:
  * XsuaaTokenFlowAutoConfigurationTest
  * JwtDecoderBuilderTest
  Changed: org.apache.http.impl.client -> org.apache.hc.client5.http.impl.classic

- Add commons-io as explicit test dependency in token-client/pom.xml
  (was previously a transitive dependency from spring-xsuaa-test)

- Rewrite Base64JwtDecoderTest to not depend on JwtGenerator
  * Removed cyclic dependency: token-client -> java-security-test ->
    java-security -> token-client
  * Create test JWT tokens manually using Java's Base64 encoder
  * Simplifies test and removes external utility dependency

- Restore compatibility Token interface for spring-security-compatibility
  * Copy com.sap.cloud.security.xsuaa.token.Token interface
  * Required for XsuaaTokenComp backwards compatibility wrapper
  * Fix javadoc broken link to prevent javadoc build failure

All modules now compile successfully with mvn clean install -DskipTests

* fix: Configure spring-security-legacy-module for Spring Boot 3.x compatibility

The spring-security-legacy-module is meant to provide the same functionality
as spring-security from version 3.6.7, allowing users to continue using the
library with Spring Boot 3.x without needing to migrate to version 4.0.

Changes:
- Override parent's Spring Boot 4.x versions with Spring Boot 3.x versions
  in the legacy module's properties section:
  * spring.boot.version: 4.0.3 → 3.5.9
  * spring.core.version: 7.0.5 → 6.2.15
  * spring.security.version: 7.0.3 → 6.5.7
  * spring.security.oauth2.version: 7.0.3 → 6.5.7
  * reactor.version: 3.8.3 → 3.8.2
  * reactor.test.version: 3.8.3 → 3.8.2

- Hardcode reactor-core and reactor-test versions to 3.8.2 (matching 3.6.7)

- Remove @disabled annotation from IdentityServicesPropertySourceFactoryTest
  (test now passes with correct Spring Boot 3.x versions)

This fixes the ConcurrentReferenceCachingMetadataReaderFactory error that
was occurring when Spring Boot 4.0.3 was being used (this class was removed
in Spring Boot 3.0+, but Spring Boot 4.0.3's internal code still referenced it).

All 114 tests now pass successfully (0 failures, 0 errors, 0 skipped).

* feat: Add SecurityHttpClient abstraction with ServiceLoader pattern

- Create SecurityHttpClient, SecurityHttpRequest, SecurityHttpResponse interfaces
- Implement JavaHttpClientFactory using Java 11 HttpClient (priority 0)
- Create token-client-apache module with ApacheHttpClientFactory (priority 100)
- Add ServiceLoader configuration for both implementations
- Update spring-security-legacy-module to depend on token-client-apache
- Add HttpClientException constructor with cause parameter
- Update BOM to include token-client-apache

* refactor: Migrate token-client services to SecurityHttpClient abstraction

- Update DefaultOAuth2TokenService to use SecurityHttpClient
- Update DefaultOAuth2TokenKeyService to use SecurityHttpClient
- Update DefaultOidcConfigurationService to use SecurityHttpClient
- Deprecate old HttpClientFactory and DefaultHttpClientFactory
- Delegate deprecated factories to SecurityHttpClientProvider
- Remove Apache HTTP Client 5 dependencies from implementations

* chore: Remove Apache HTTP Client 5 dependency from token-client

Token-client now uses Java 11 HttpClient by default through the SecurityHttpClient abstraction.
Apache HTTP Client support is available via token-client-apache module.

* test: Update all test files to use SecurityHttpClient mocks

Replace Apache HTTP Client mocks with SecurityHttpClient mocks across
all test files in token-client, java-security, spring-security, and
spring-security-legacy modules.

Changes:
- Replace CloseableHttpClient mocks with SecurityHttpClient mocks
- Remove HttpClientResponseHandler callback pattern
- Replace with direct .thenReturn(response) for SecurityHttpResponse
- Update HttpClientTestFactory to create SecurityHttpResponse objects
- Replace any(HttpGet.class) with any(SecurityHttpRequest.class)
- Replace any(HttpPost.class) with any(SecurityHttpRequest.class)
- Add missing HttpHeaders imports where needed
- Fix mock response setup to provide enough responses for all test calls
- Rename deprecated HTTP client factory tests to .skip

Test results:
- token-client: 258 tests pass
- java-security: 319 tests pass (2 skipped)
- spring-security: 114 tests pass
- spring-security-legacy: 114 tests pass

Also includes:
- Rename spring-security-legacy-module to spring-security-legacy
- Add LegacyHttpClientWrapper for backward compatibility
- Update ApacheHttpClientAdapter implementation

* fixed typing error

* fix: Resolve GitHub Advanced Security bot code findings

- Add missing @OverRide annotations to JavaSecurityContextHolderStrategy methods
- Suppress deprecation warnings for intentional deprecated API usage in tests
- Fix code scanning findings for XsuaaTokenComp and Apache HTTP Client tests

* fix: Replace @link with @code for cross-module Javadoc reference

Fix Javadoc generation error where @link tag referenced ApacheHttpClientFactory
from token-client-apache module which is not available during token-client
Javadoc generation. Changed to @code tag to avoid broken reference.

* fix: Remove spring-xsuaa dependencies and update workflow

- Remove spring-xsuaa dependency from java-security-it/pom.xml
- Delete tests that depend on removed spring-xsuaa module:
  - SpringXsuaaPerformanceIT.java
  - SpringSSRFAttackTest.java
- Remove spring-xsuaa-it and spring-security-xsuaa-usage from CI workflow
- Skip java-security-it tests in workflow (has API compatibility issues)

The spring-xsuaa module was removed in v4.0.0

* fix: Address log injection and SSRF vulnerabilities

- Add LogSanitizer utility class to sanitize user-provided data before logging
- Apply LogSanitizer to all identified log injection points:
  - DefaultOAuth2TokenKeyService: sanitize URI and headers in debug logs
  - SpringOAuth2TokenKeyService: sanitize URI and params in debug logs
  - OAuth2TokenKeyServiceWithCache: sanitize keyUri in error log
  - JwtAudienceValidator: sanitize audiences in debug log
  - ValidationResults: sanitize error descriptions in warning log
  - AbstractTokenAuthenticator: sanitize error messages in warning log
- Add URI validation to prevent SSRF attacks:
  - Validate URI scheme (only HTTP/HTTPS allowed)
  - Validate URI host (must be present and non-empty)
- Maintain all logging information while preventing control character injection

* fix: Suppress deprecation warning for setConnectTimeout in ApacheHttpClientFactory

Add @SuppressWarnings("deprecation") annotation to constructor to address
CodeQL finding about deprecated Builder.setConnectTimeout() method usage.
The deprecated method is intentionally used for backward compatibility with
Apache HttpClient 4.5.x.

* fix: Add @SuppressWarnings to XsuaaTokenCompTest for deprecated API usage

Add class-level @SuppressWarnings("deprecation") to XsuaaTokenCompTest to
suppress CodeQL warnings about using deprecated XsuaaTokenComp.createInstance()
methods. This is intentional as the test class specifically tests the deprecated
XsuaaTokenComp class for backward compatibility purposes.

* fix: Replace deprecated method calls with non-deprecated alternatives

Replace deprecated API calls to address CodeQL findings:

- XsuaaTokenCompTest: Replace getSubdomain() with getClaimAsMap() to read
  subdomain from external attributes claim
- XsuaaTokenCompTest: Replace getSubaccountId() with getZoneId() as the
  recommended alternative
- SecurityTestRuleTest: Replace execute() with executeOpen() for HttpClient
- SecurityTestExtensionTest: Replace execute() with executeOpen() for HttpClient

These changes eliminate deprecated API usage while maintaining the same test
behavior and assertions.

* Revert "fix: Replace deprecated method calls with non-deprecated alternatives"

This reverts commit a26a3f9.

* Potential fix for code scanning alert no. 445: Deprecated method or constructor invocation

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Signed-off-by: NiklasHerrmann21 <[email protected]>

* Potential fix for code scanning alert no. 444: Deprecated method or constructor invocation

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Signed-off-by: NiklasHerrmann21 <[email protected]>

* Potential fix for code scanning alert no. 443: Deprecated method or constructor invocation

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Signed-off-by: NiklasHerrmann21 <[email protected]>

* fix: Properly close HttpClient resources in try-with-resources blocks

Fix resource leaks in Copilot Autofix changes by ensuring both
CloseableHttpClient and ClassicHttpResponse are properly closed in
try-with-resources blocks. Remove unnecessary HttpClientResponseHandler
import and simplify lambda usage.

* fix: Correct import for CloseableHttpClient

Use org.apache.hc.client5.http.impl.classic.CloseableHttpClient
instead of org.apache.hc.client5.http.classic.CloseableHttpClient
to fix compilation error.

* fix: Revert to using deprecated execute() with @SuppressWarnings

The response handler approach caused 'Stream closed' errors because
HttpClient closes the response after the handler returns. Reverted
to using the deprecated execute() method directly with try-with-resources
and @SuppressWarnings("deprecation") annotation.

This is acceptable for test code testing deprecated functionality.
The CodeQL alerts will remain as informational notices but won't
block the PR.

* fix: Address remaining SSRF and log injection vulnerabilities

Add URI validation and log sanitization to address CodeQL security findings:

SSRF Prevention:
- Add validateUri() method to ApacheHttpClientAdapter to validate URIs
  before creating HTTP requests
- Add validateUri() method to JavaHttpClientAdapter to validate URIs
  before executing requests
- Validation ensures only HTTP/HTTPS schemes are allowed and host is present
- Prevents server-side request forgery attacks by rejecting malicious URIs

Log Injection Prevention:
- Add LogSanitizer.sanitize() calls in DefaultOAuth2TokenService for
  tokenUri and parameters logging (lines 77, 86, 91)
- Sanitizes control characters to prevent log injection attacks
- Complements existing sanitization in other OAuth2 service classes

These fixes address the remaining Critical and High severity CodeQL findings
and complete the security hardening for the major 4.0.0 release.

* refactor: Replace token-client-apache module with simple HttpRequestExecutor interface

Breaking Changes:
- Remove token-client-apache module completely
- Replace ApacheHttpClientAdapter with generic CustomHttpClientAdapter
- Switch default HTTP client from Apache HttpClient 4.x to Java 11 HttpClient

New Features:
- Add HttpRequestExecutor functional interface for custom HTTP clients
- Add CustomHttpClientAdapter to wrap any HTTP client implementation
- Add comprehensive CUSTOM_HTTP_CLIENT.md documentation with examples
- Support for Apache HttpClient 4.x, 5.x, OkHttp, and any other HTTP client

Benefits:
- No need for separate adapter modules per HTTP client library
- Future-proof: works with any HTTP client version
- Simpler maintenance: users manage their own HTTP client implementations
- Zero breaking changes when HTTP client libraries update

Migration:
- Default users: No changes needed (automatic Java 11 HttpClient)
- Custom HTTP client users: Implement HttpRequestExecutor interface
- See CUSTOM_HTTP_CLIENT.md for detailed migration examples

Modified Files:
- Remove: token-client-apache module (adapter, factory, SPI config)
- Remove: LegacyHttpClientWrapper (unused)
- Remove: Apache HttpClient dependency from spring-security-basic-auth sample
- Update: POMs (root, bom, spring-security-legacy)
- Update: token-client README.md (remove Apache HttpClient references)
- Add: HttpRequestExecutor interface and CustomHttpClientAdapter
- Add: CUSTOM_HTTP_CLIENT.md with migration guide and examples

* feat: Update spring-webflux-security-hybrid-usage sample to showcase spring-security-legacy-module

This sample now demonstrates how customers can use the spring-security-legacy-module
for Spring Boot 3.x compatibility while the main library has moved to Spring Boot 4.x.

Changes:
- Update library version from 3.6.7 to 4.0.0
- Replace resourceserver-security-spring-boot-starter with spring-security-legacy-module
- Update Spring Boot from 3.5.3 to 3.5.9 (matching legacy module)
- Add Spring Security OAuth2 dependencies (6.5.7) required for reactive JWT support
- Update README.md with detailed explanation of legacy module usage
- Rename sample description to highlight legacy module showcase

Purpose:
This sample serves as a reference for customers who:
- Cannot immediately upgrade to Spring Boot 4.x
- Want to use the latest 4.0.0 security features and fixes
- Need time to plan their Spring Boot 4.x migration

The sample demonstrates that the legacy module provides full functionality
for hybrid XSUAA/IAS token validation in reactive WebFlux applications
while maintaining Spring Boot 3.x compatibility.

* fix: Use jakarta.servlet-api 6.1.0 in webflux sample (consistent with parent POM)

* feat: Add spring-security-starter-legacy for Spring Boot 3.x compatibility

This commit introduces a new Spring Boot starter module specifically for
Spring Boot 3.x applications, enabling customers to use the latest 4.0.0
security features while remaining on Spring Boot 3.x.

## New Module: spring-security-starter-legacy

- Artifact: `resourceserver-security-spring-boot-starter-legacy`
- Purpose: Spring Boot 3.x compatibility layer
- Spring Boot version: 3.5.9
- Spring Security version: 6.5.7
- Spring Framework version: 6.2.15

## Changes

### Core Library
- Add `spring-security-starter-legacy` module with AutoConfiguration support
- Exclude Spring Boot 4.x dependencies from `spring-security-legacy` module
  - Excludes: spring-boot-starter-restclient, spring-boot-http-client,
    spring-boot-jackson, etc.
  - Prevents NoSuchMethodError from version conflicts

### Samples
- Update `spring-webflux-security-hybrid-usage` to use the new starter
- Simplify sample POM by leveraging starter dependencies
- Remove manual bean definitions - now provided by AutoConfiguration
- Fix: AuthConverter is now auto-configured by HybridAuthorizationAutoConfiguration
- Update README with clear explanation of legacy starter usage

### Build System
- Add spring-security-starter-legacy to parent POM modules
- Add spring-security-starter-legacy to BOM

## Migration Path

Applications on Spring Boot 3.x should use:
```xml
<dependency>
    <groupId>com.sap.cloud.security</groupId>
    <artifactId>resourceserver-security-spring-boot-starter-legacy</artifactId>
    <version>4.0.0</version>
</dependency>
```

Applications on Spring Boot 4.x should use:
```xml
<dependency>
    <groupId>com.sap.cloud.security</groupId>
    <artifactId>resourceserver-security-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>
```

## Fixes
- Fix version conflicts between Spring Boot 3.x and 4.x dependencies
- Tests now pass successfully in spring-webflux-security-hybrid-usage sample

Co-authored-by: Claude <[email protected]>

* docs: Add comprehensive documentation for Major Release 4.0.0

- Add detailed CHANGELOG entry for version 4.0.0 with:
  * Breaking changes (Spring Boot 4.x, Jakarta EE 10 upgrades)
  * New features (Spring Boot 3.x compatibility layer, HTTP client abstraction)
  * Removed modules (spring-xsuaa, spring-security-compatibility, etc.)
  * Security fixes (SSRF, log injection vulnerabilities)
  * Dependency upgrades

- Update root README.md:
  * Add "What's New in 4.0.0" section with migration guidance
  * Update Prerequisites to clarify Spring Boot 4.x requirement
  * Document Spring Boot 3.x compatibility via legacy modules
  * Add version support table comparing standard vs legacy starters
  * Update Spring Boot applications section with two-starter approach
  * Remove references to deleted spring-xsuaa module
  * Update token-client section about HTTP client changes
  * Update BOM version from 3.6.8 to 4.0.0
  * Add Migration Guide section with quick links

- Add MIGRATION_4.0.md comprehensive migration guide:
  * Two migration paths (Spring Boot 4.x upgrade vs 3.x compatibility)
  * Step-by-step instructions for each path
  * Detailed removed modules section with replacements
  * Token client HTTP client migration guide
  * Troubleshooting section for common issues

This completes the documentation updates for the Major Release 4 PR.
All critical changes are now documented for users migrating from 3.x.

* fix: Remove spring-security-compatibility dependency from spring-security-hybrid-usage sample

The spring-security-compatibility module was removed in Major Release 4.
This commit updates the sample to work without it:

- Update pom.xml:
  * Remove spring-security-compatibility dependency (module deleted)
  * Update sap.cloud.security.version from 3.6.7 to 4.0.0
  * Remove explicit Spring Boot version overrides (use parent version)
  * Remove explicit junit-vintage-engine version (use parent version)

- Update TestController.java:
  * Remove /comp/sayHello endpoint that used XsuaaTokenComp
  * Remove imports for deleted compatibility classes
  * Keep main /sayHello endpoint unchanged

The sample now compiles successfully with Spring Boot 3.5.3 and the
standard resourceserver-security-spring-boot-starter 4.0.0.

Note: Some tests have compatibility issues with Spring Boot 3.5.3 vs
the java-security-test SecurityTestRule, but the application builds
and runs correctly.

* refactor: Rename spring-security-legacy-module to spring-security-legacy

Simplify artifact naming by removing "-module" suffix for consistency
with other module names in the project.

Changes:
- spring-security-legacy/pom.xml: Update artifactId and name from
  spring-security-legacy-module to spring-security-legacy

- spring-security-starter-legacy/pom.xml: Update dependency reference
  from spring-security-legacy-module to spring-security-legacy

- bom/pom.xml: Update dependency management entry from
  spring-security-legacy-module to spring-security-legacy

The directory name was already "spring-security-legacy", so this makes
the artifactId match the directory structure.

All modules build successfully with the new naming.

* docs: Fix all references to spring-security-legacy-module and token-client-apache

Replace inconsistent naming and clarify HTTP client changes across all
documentation files.

Changes to spring-security-legacy-module references:
- CHANGELOG.md: Update module name from spring-security-legacy-module
  to spring-security-legacy throughout
- MIGRATION_4.0.md: Correct artifactId in all code examples
- PR_SUMMARY.md: Update module references in summary tables

Changes to token-client-apache references:
- Remove all mentions of token-client-apache module (never released)
- Clarify that Apache HttpClient is no longer the default
- Emphasize Java 11 HttpClient as the new default
- Update CHANGELOG.md to reflect HTTP client change as breaking change
- Update MIGRATION_4.0.md with clearer migration path
- Update README.md to remove token-client-apache from removed modules list

token-client/README.md major updates:
- Remove outdated Apache HttpClient dependency from Java EE setup
- Update XsuaaTokenFlows initialization example (no HttpClient param)
- Replace Apache HttpClient logging docs with Java HttpClient docs
- Rewrite performance section to cover both Java HttpClient and custom
  Apache HttpClient implementations
- Add reference to CUSTOM_HTTP_CLIENT.md for Apache HttpClient users
- Remove obsolete HttpClientFactory code examples
- Update version from 3.6.8 to 4.0.0 in examples

All documentation now correctly states:
- Module is "spring-security-legacy" (not spring-security-legacy-module)
- Apache HttpClient was replaced, not removed as a separate module
- Java 11 HttpClient is now the default (no external dependencies)
- Apache HttpClient available via custom implementation (see guide)

* docs: Add SAP Cloud SDK HttpClientAccessor integration example

Add dedicated section showing how to integrate token-client 4.0.0 with
SAP Cloud SDK's HttpClientAccessor for destination-based HTTP clients.

This addresses a common use case where users leverage Cloud SDK's
HttpClientAccessor.getHttpClient(destination) to obtain configured
HttpClients with proxy, auth, and connection pooling from destinations.

New section includes:
- Complete code example wrapping Cloud SDK's HttpClient in HttpRequestExecutor
- Side-by-side migration comparison (3.x vs 4.0.0)
- Benefits list highlighting Cloud SDK feature compatibility
- Proper error handling and resource management

The example shows that the 3.x pattern:
  new DefaultOAuth2TokenService((CloseableHttpClient) HttpClientAccessor.getHttpClient(destination))

Can be migrated to 4.0.0 with:
  HttpRequestExecutor -> CustomHttpClientAdapter -> DefaultOAuth2TokenService

This maintains full compatibility with Cloud SDK's destination management
while using the new HTTP client abstraction.

* fix: Remove @EnableWebSecurity from WebFlux sample to prevent Servlet API dependency

WebFlux applications should not use @EnableWebSecurity as it triggers Servlet-based
security configuration. The SecurityWebFilterChain bean is sufficient for reactive
security configuration.

Fixes ClassNotFoundException: jakarta.servlet.Filter during Cloud Foundry deployment.

* refactor: Remove Apache HttpClient dependencies from POMs

Apache HttpClient (4.x and 5.x) is no longer part of the library. Version 4.0.0 uses
Java 11 HttpClient as the default HTTP client implementation.

Changes:
- Removed apache.httpclient5.version and apache.httpclient.version properties from parent POM
- Removed httpclient, httpclient5, httpcore5, and httpcore5-h2 from dependencyManagement
- Removed httpclient5 dependency from spring-security-starter
- Removed httpclient5 dependency from spring-security-starter-legacy
- Removed httpclient5 and httpcore5 test dependencies from java-security-test

Users who need Apache HttpClient can integrate it using the HttpRequestExecutor interface
as documented in token-client/CUSTOM_HTTP_CLIENT.md

* fix: Handle IAS groups claim as both String and List in WebFlux sample

IAS tokens can have the 'groups' claim as either a String (single group) or
List<String> (multiple groups). The previous code only handled List<String>,
causing authorization failures when tokens had a single group as String.

Changes:
- Modified deriveAuthoritiesFromGroup() to check the type of groups claim
- Handle String: directly add as single authority
- Handle List<String>: process as before
- Fixes 401 Authorization Denied for IAS tokens with single group string

Example: {"groups": "Read"} now correctly grants 'Read' authority

* chore: Add *.pem to .gitignore to prevent committing certificates

* debug: Add detailed logging to trace JWT processing in WebFlux sample

* debug: Add JWT converter entry log and fix anyExchange rule

* debug: Enable DEBUG logging for SecurityConfiguration

* feat: Upgrade spring-security-hybrid-usage sample to Spring Boot 4.0.3

- Update spring-boot-starter-parent from 3.5.3 to 4.0.3
- Remove obsolete Apache HttpClient dependency (no longer needed with new token-client)
- Add spring-boot-webmvc-test dependency for test support
- Update AutoConfigureMockMvc import to new Spring Boot 4 package structure
- Remove obsolete JUnit 4 test (JUnit 5 tests provide same coverage)
- Remove unused /comp/sayHello route and related compatibility tests

* refactor: Clean up spring-webflux-security-hybrid-usage sample and add debug logging

- Remove debug logging from SecurityConfiguration
- Remove /actuator/health endpoint configuration
- Update POM artifact name to match actual usage
- Add comprehensive debug logging to ReactiveHybridJwtDecoder for troubleshooting XSUAA token validation

* chore: Remove unused spring-boot-starter-actuator dependency

* docs: Add connection pooling documentation to token-client README

- Document timeout settings and connection pool behavior for Java HttpClient
- Add JVM system properties for explicit pool limits
- Reference CUSTOM_HTTP_CLIENT.md for Apache HttpClient alternative
- Simplify migration guide to reference README instead of duplicating info

* feat: Add backward compatibility for Apache HttpClient 4

To address customer concerns about the removal of Apache HttpClient 4
support, this commit adds deprecated constructors and an adapter to
provide a smooth migration path while encouraging adoption of the new
Java 11 HttpClient default.

Changes:
- Add ApacheHttpClient4Adapter (deprecated) to wrap CloseableHttpClient
- Add deprecated constructors to DefaultOAuth2TokenKeyService
- Add deprecated constructors to DefaultOAuth2TokenService (2 variants)
- Add deprecated constructor to DefaultOidcConfigurationService
- Add Apache HttpClient 4.5.14 as optional dependency in token-client
- Fix test ambiguity by adding explicit SecurityHttpClient casts
- Remove debug logging from ReactiveHybridJwtDecoder

Documentation:
- Add comprehensive APACHE_HTTPCLIENT_MIGRATION.md guide with 4
  migration paths and detailed examples
- Update CHANGELOG.md with breaking change notice and migration info
- Update token-client README.md with HTTP client changes section

Deprecation Timeline:
- Version 4.0.0: Deprecated with backward compatibility
- Version 5.0.0: Complete removal planned

Migration Paths:
1. Use default Java 11 HttpClient (recommended, no code changes)
2. Continue with Apache HttpClient 4 via deprecated constructors
3. Use ApacheHttpClient4Adapter explicitly (stepping stone)
4. Implement custom HttpRequestExecutor (future-proof)

All tests pass (258 tests). Code scanners satisfied with optional
dependency scope.

* feat: Update java-tokenclient-usage sample to demonstrate Apache HttpClient 4 backward compatibility

This sample now showcases how existing applications using Apache HttpClient 4
can continue to work with version 4.0.0+ through deprecated constructors.

Changes:
- Update to version 4.0.0 in pom.xml
- Refactor HelloTokenClientServlet to demonstrate deprecated constructor usage
- Add custom Apache HttpClient 4 configuration with connection pooling
- Add @SuppressWarnings("deprecation") to show proper usage
- Add proper resource cleanup in destroy() method
- Include inline migration comments showing alternative approaches

Documentation:
- Update README.md with deprecation notice and migration guidance
- Add code highlights section explaining the demonstration
- Link to APACHE_HTTPCLIENT_MIGRATION.md for detailed migration paths

Purpose:
1. Testing: Validates backward compatibility layer works correctly
2. Example: Shows customers how to temporarily maintain existing integration
3. Reference: Provides working code for migration planning

Build Result:
- ✅ Successfully compiles with expected deprecation warning
- ✅ Shows proper usage of deprecated constructors
- ✅ WAR package created successfully

* feat: Restore HttpClientFactory backward compatibility with Apache HttpClient 4

- HttpClientFactory and DefaultHttpClientFactory now return CloseableHttpClient
  again (like in 3.x) for full backward compatibility
- Apache HttpClient 4 dependency changed from optional to compile scope
  (required for overload resolution in dependent modules)
- Use normal imports instead of fully qualified names in deprecated constructors
- Document 3-step deprecation plan:
  - 4.x: Full compatibility, CloseableHttpClient return type
  - 5.0.0: Return type changes to SecurityHttpClient
  - 6.0.0: HttpClientFactory removed entirely

* docs: Update documentation to reflect Apache HttpClient as transitive dependency

Apache HttpClient 4 is now a compile dependency of token-client (not optional),
so users don't need to add it explicitly. Updated documentation to reflect this:
- APACHE_HTTPCLIENT_MIGRATION.md: clarified Apache HttpClient is transitive
- README.md: removed misleading optional dependency comment

* docs: Update CHANGELOG and MIGRATION guide to reflect HttpClientFactory backward compatibility

- CHANGELOG: Remove incorrect "Breaking Change" statements about Apache HttpClient
- CHANGELOG: Document that HttpClientFactory still returns CloseableHttpClient
- MIGRATION_4.0.md: Add Option 2 for continuing to use deprecated Apache HttpClient constructors
- Clarify that Apache HttpClient 4 is included as transitive dependency

* refactor: Remove unnecessary httpclient5 dependency and update documentation

Code changes:
- Remove httpclient5 compile dependency from spring-security and java-security
  (it was never used in production code, only in tests)
- Replace deprecated HttpClientFactory.create() with SecurityHttpClientProvider.createClient()
  in spring-security AutoConfiguration classes
- Migrate java-security-test tests from Apache HttpClient 5 to Java 11 HttpClient
- spring-security-legacy keeps using HttpClientFactory (Apache HttpClient 4) for
  maximum backward compatibility with 3.x behavior

Documentation updates:
- token-client/README.md: Mark HttpClientFactory as deprecated, show recommended approach
- java-security/README.md: Update HybridTokenAuthenticator example to use SecurityHttpClientProvider
- spring-security-legacy/README.md: Fix version (4.0.0), correct starter artifact name,
  add note about Apache HttpClient 4 usage

* refactor: Remove ApacheHttpClient4Adapter and add CloseHandler to CustomHttpClientAdapter

- Remove redundant ApacheHttpClient4Adapter class (was just a thin wrapper)
- Add CloseHandler functional interface to CustomHttpClientAdapter for proper resource cleanup
- Add new constructor CustomHttpClientAdapter(executor, closeHandler) to support closing underlying HTTP clients
- Update deprecated constructors in service classes to use CustomHttpClientAdapter directly with ApacheHttpClient4Executor
- Update documentation to reflect the simplified architecture

* feat: Update java-tokenclient-usage sample with X.509 mTLS support and improved logging

This commit enhances the java-tokenclient-usage sample to properly demonstrate
Apache HttpClient 4 backward compatibility with X.509 certificate-based authentication:

- Configure Apache HttpClient 4 with SSLContextFactory for mTLS authentication
- Add proper SSL context setup with client certificates from XSUAA service binding
- Include connection pooling configuration for production use
- Update JavaDoc to document X.509 certificate support
- Set default log level to WARN to prevent DEBUG logs appearing as errors in Cloud Foundry
- Add commented option to enable DEBUG logs for development

The sample now successfully demonstrates:
- Certificate-based authentication (mTLS) with XSUAA
- Deprecated Apache HttpClient 4 constructor usage
- Proper resource cleanup in destroy() method
- Connection pooling configuration

* docs: Fix token exchange mode configuration values

Correct the configuration property values for token exchange mode from
`provide_xsuaa`/`force_xsuaa` to `providexsuaa`/`forcexsuaa` to match
the actual implementation in TokenExchangeMode.fromString().

The enum names remain PROVIDE_XSUAA and FORCE_XSUAA, but the lowercase
configuration values must be written without underscores.

Updated in:
- spring-security/README.md
- spring-security-legacy/README.md

* chore: Update java-security-usage samples to version 4.0.0

Update sap.cloud.security.version from 3.6.7 to 4.0.0 in:
- samples/java-security-usage-ias
- samples/java-security-usage

Both samples compile and pass tests successfully with the new version.

* fix: Update spring-security-basic-auth to use legacy starter

Changes:
- Remove explicit Spring Boot dependency versions (rely on parent)
- Switch to resourceserver-security-spring-boot-starter-legacy for Spring Boot 3.x compatibility
- Update sap.cloud.security.version to 4.0.0

This sample remains on Spring Boot 3.5.4 as a demonstration of the legacy module.
Note: Some tests fail with 401 instead of expected 403/200 - this appears to be
a pre-existing issue with token authentication in the test setup.

* feat: Migrate spring-security-basic-auth to Spring Boot 4.0.3

Changes:
- Update Spring Boot from 3.5.4 to 4.0.3
- Switch to resourceserver-security-spring-boot-starter (from legacy)
- Update SecurityConfiguration to use Lambda DSL API
- Update test imports: AutoConfigureMockMvc package changed to org.springframework.boot.webmvc.test.autoconfigure
- Replace @MockBean with manual mock creation in TokenBrokerTestConfiguration
- Add spring-boot-webmvc-test dependency for test support
- Add maven-compiler-plugin and maven-surefire-plugin to build

Application compiles and runs successfully.

Known Issue: 3/7 tests fail with 401 instead of expected 200/403 status codes.
This appears to be related to token validation changes in Spring Boot 4 or the
mock setup. The core functionality (compilation, security config, token broker)
works correctly. Tests: rejectsTokenWithoutScopes, rejectsTokenWithWrongScope,
acceptsTokenWithValidScope need investigation.

* fix: Handle null app_tid in X-zid header for Java 21+ compatibility

Fixes compatibility issue with Java 21+ HttpClient which strictly
rejects null header values.

XsuaaJwtSignatureValidator now checks if token.getAppTid() is null
before adding X-zid header, preventing NullPointerException when
fetching token keys from XSUAA service.

This fix enables spring-security-basic-auth sample to work with
Spring Boot 4.0.3 and Java 21+.

* fix: Remove spring-boot-starter-restclient from token-client to reduce transitive dependencies

BREAKING CHANGE: Replaced spring-boot-starter-restclient with minimal jackson-databind dependency

This change addresses user feedback about excessive transitive dependencies from token-client
that caused conflicts in downstream projects. Users had to manually exclude Spring Boot modules
which should not have been required.

Changes:
- Removed: spring-boot-starter-restclient (brought 20+ transitive dependencies)
  - Eliminated: spring-boot-starter-logging, spring-boot-autoconfigure, snakeyaml, micrometer
- Added: com.fasterxml.jackson.core:jackson-databind (minimal JSON processing)
- Added: jakarta.annotation-api to spring-security module (was previously transitive)

Impact:
- Reduces compile-scope transitive dependencies by ~52%
- Removes all Spring Boot dependencies from token-client compile scope
- Eliminates logging framework conflicts (Logback, Log4j2)
- All 372 tests passing (258 token-client + 114 spring-security)

Users no longer need to exclude dependencies from token-client.

* refactor: Rename legacy modules to spring-security-3 and spring-security-starter-3

Replace "legacy" naming with "-3" suffix to better indicate Spring Boot 3.x compatibility.
This makes it clearer that these modules target Spring Boot 3.x rather than being outdated code.

Changes:
- Renamed spring-security-legacy → spring-security-3
- Renamed spring-security-starter-legacy → spring-security-starter-3
- Updated artifact IDs in all POM files
  - spring-security-3
  - resourceserver-security-spring-boot-starter-3
- Updated all documentation references:
  - README.md: Version support table and module descriptions
  - CHANGELOG.md: Feature descriptions and module references
  - MIGRATION_4.0.md: Migration paths and module names
  - PR_SUMMARY.md: All legacy references replaced
  - spring-security-3/README.md: Starter name updated
  - samples/spring-webflux-security-hybrid-usage: POM and README updated

Semantic improvements:
- "Legacy Starter" → "Spring Boot 3 Starter"
- "Legacy module" → "Spring Boot 3 module"
- Emphasizes Spring Boot 3.x compatibility rather than legacy status

All module builds verified successfully.

* chore: Prepare release 4.0.0

Update all version references from 4.0.0-RC1/RC2 to final release version 4.0.0.

Changes:
- Updated version in all POM files to 4.0.0
- Root pom.xml: 4.0.0-RC2 → 4.0.0
- All module POMs updated to 4.0.0
- All sample application POMs updated to 4.0.0
- BOM version updated to 4.0.0

This is the final release version without any release candidate suffix.

Total files updated: 18 POM files

* fix: Remove deprecated HttpClientFactory usage in java-security-usage sample

The sample was using the deprecated HttpClientFactory.create() method which
returns CloseableHttpClient, but XsuaaTokenAuthenticator.withHttpClient()
now expects SecurityHttpClient.

Since the default HTTP client is used by default, removed the explicit
HTTP client configuration to use the new Java 11 HttpClient implementation.

Fixes build failure in GitHub Actions.

* refactor: Rename spring-security-starter-3 to spring-security-3-starter

Aligns naming convention: library module comes first (spring-security-3),
then type (starter). Updates all references in POMs, documentation, and samples.

- Renamed directory: spring-security-starter-3 → spring-security-3-starter
- Updated artifactId: resourceserver-security-spring-boot-starter-3 → resourceserver-security-spring-boot-3-starter
- Updated all references in parent pom, bom, samples, and documentation

* removed specific values from the vars.yml file

* test: Restore and fix HttpClientFactory tests, add SecurityHttpClientFactory tests

- Rename .skip files back to .java for HttpClientFactory tests
- Fix deprecated HttpClientFactory tests to work with Apache HttpClient
- Add comprehensive tests for SecurityHttpClientFactory
- Create TestSecurityHttpClientFactory to verify ServiceLoader priority mechanism
- Add META-INF service configuration for test factory

All factory tests now pass (5 tests total):
- DefaultHttpClientFactoryTest: 1 test (redirect behavior)
- HttpClientFactoryTest: 1 test (factory creation)
- SecurityHttpClientFactoryTest: 3 tests (creation, null identity, priority)

* docs: Remove PR_SUMMARY.md and fix CHANGELOG.md accuracy

- Remove PR_SUMMARY.md (not needed in repository)
- Fix CHANGELOG to correctly state that deprecated modules were removed (not just excluded)
- Clarify that Apache HttpClient 4.5.14 remains as a dependency for backward compatibility
- Fix artifact ID reference (spring-security-3-starter)
- Add version 3.6.9 bugfix entry to CHANGELOG
- Add missing bug fixes and improvements from recent commits

* docs: Update all READMEs to reflect 4.0.0 changes

- Update version references from 3.6.8 to 4.0.0 in all module READMEs
- Replace spring-xsuaa references with spring-security-3
- Fix artifact ID from resourceserver-security-spring-boot-starter-legacy to resourceserver-security-spring-boot-3-starter
- Update token-client README to reference spring-security-3 instead of spring-xsuaa
- Update samples README to remove deprecated spring-security-xsuaa-usage reference
- Reorganize samples README by Spring Boot version (4.x vs 3.x)
- Update java-security-test README to reference spring-security-3

All READMEs now accurately reflect the Major Release 4.0.0 module structure.

* docs: Clarify spring-security-3 vs spring-xsuaa relationship in CHANGELOG

- Move 'identical APIs to spring-xsuaa' note from spring-security-3 feature description to Removed Modules section
- spring-security-3 is primarily the Spring Boot 3.x compatibility layer for spring-security
- spring-xsuaa users should migrate to spring-security (Boot 4.x) or spring-security-3 (Boot 3.x)
- Clarify that both replacement modules provide identical APIs to spring-xsuaa

This makes the migration path clearer: spring-xsuaa users choose between
spring-security (upgrade to Boot 4.x) or spring-security-3 (stay on Boot 3.x).

* fixed changelog

* added migration guide to changelog

* docs: Fix sample names in README

- java-security-xsuaa-usage → java-security-usage
- java-security-identity-usage → java-security-usage-ias
- Also fix typo: sap-java-builpack-api-usage → sap-java-buildpack-api-usage

* docs: Update migration guide with accurate upgrade timeline and HTTP client support details

- Change Spring Boot 4.x upgrade recommendation from "within your next major release cycle" to "as soon as possible"
- Clarify Apache HttpClient 4 support is maintained via deprecated constructors (removed in 5.0.0)
- Add explicit mention of custom HTTP client support (Apache HttpClient 5, OkHttp, etc.)

* docs: Remove duplicate Token Client HTTP Client Changes section

Remove the duplicate "Token Client: Apache HttpClient → Java 11 HttpClient" section from under "Removed Modules" and keep only the comprehensive "Token Client HTTP Client Changes" section.

* docs: Add concrete migration examples for Token Client HTTP client changes

Add practical migration examples including:
- Before/After Maven dependencies (3.6.8 → 4.0.0)
- Option 1: Default Java 11 HttpClient (recommended)
- Option 2: Deprecated Apache HttpClient constructors with code example
- Option 3: Custom Apache HttpClient 5 with Maven dependency

* docs: Consolidate and simplify documentation

Spring Security READMEs:
- Replace spring-security-3 README with concise version referencing spring-security README
- Add note about Spring Boot 3.x compatibility in spring-security README
- Remove duplicate documentation (543 lines → 51 lines)

HTTP Client Documentation:
- Simplify APACHE_HTTPCLIENT_MIGRATION.md (377 lines → 193 lines)
- Simplify CUSTOM_HTTP_CLIENT.md (435 lines → 252 lines)
- Clarify that Apache HttpClient 4 support via deprecated constructors ends in 5.0.0
- Clarify that Apache HttpClient 4/5 support going forward is via custom HttpRequestExecutor only
- Remove confusing statements about "native support" for Apache HttpClient

All documentation now clearly states:
- Java 11 HttpClient is the default (recommended)
- Apache HttpClient 4 deprecated constructors (removed in 5.0.0)
- Apache HttpClient 4/5 can be used via custom HttpRequestExecutor (not deprecated, future-proof)

* docs: Remove duplicate Apache HttpClient 5 example from migration guide

Reference CUSTOM_HTTP_CLIENT.md instead to avoid duplication

* docs: Improve HTTP client migration documentation

APACHE_HTTPCLIENT_MIGRATION.md:
- Add HttpClientFactory → SecurityHttpClientProvider migration example in Option 1
- Add HttpClientFactory.create() example to Option 2 (deprecated)
- Reword Option 3 title to "Recommended for Custom Configurations" (remove "not deprecated" as that's obvious)
- Remove OkHttp references

CUSTOM_HTTP_CLIENT.md:
- Move Apache HttpClient 4 section to top (before Apache HttpClient 5)
- Reference built-in ApacheHttpClient4Executor (deprecated) with recommendation to copy implementation for long-term support
- Remove standalone Apache HttpClient 4 code example section at bottom (duplicate)
- Remove all OkHttp examples and references

* chore: Update Jetty to 12.1.7

Update Eclipse Jetty from 12.1.6 to 12.1.7 to address potential security vulnerabilities.

Note: Jetty is only used in java-security-test module for testing purposes (embedded Jetty server for Java EE servlet tests). It is not part of the runtime dependencies.

* docs: Rename CUSTOM_HTTP_CLIENT.md to CUSTOM_HTTPCLIENT.md

Rename file to match naming convention of APACHE_HTTPCLIENT_MIGRATION.md.
Update all references across documentation files.

* fix: Correct BOM to include all required modules with correct groupIds

Critical fix for BOM (java-bom):
- Fix spring-security: changed from wrong groupId (xsuaa) to correct (com.sap.cloud.security)
- Remove java-security-it (integration tests only, not a library)
- Remove spring-security-starter (directory name, not artifactId)
- Remove spring-security-3-starter (directory name, not artifactId)
- Remove deleted modules (spring-xsuaa, spring-xsuaa-test, spring-security-compatibility)

The main issue: spring-security was not being managed by the BOM due to wrong
groupId, causing Maven to fall back to old 3.x versions from transitive
dependencies, resulting in NoSuchMethodError: withHttpClient(SecurityHttpClient).

Fixes customer issue in 4.0.0-RC2.

* refactor: Extract Spring classes from token-client to token-client-spring module

Move Spring-based OAuth2 token service implementations to a separate module
to avoid classloader issues when token-client is used in environments where
Spring is not available (e.g., SAP Java Buildpack's Tomcat lib folder).

Moved classes:
- XsuaaOAuth2TokenService
- SpringOAuth2TokenKeyService
- SpringOidcConfigurationService

This is a breaking change: applications using these classes must now add
the token-client-spring dependency.

* ci: Add java-security-it integration tests to build workflow

- Add dedicated step to run java-security-it integration tests after main build
- Remove OkHttp reference from README as it's not included in custom HTTP client examples

* Migrate java-security-it tests to JUnit 5 and SecurityHttpClient API

- Migrate JUnit 4 tests (IasIntegrationTest, XsuaaIntegrationTest, XsuaaMultipleBindingsIntegrationTest) to JUnit 5
  - Replace @ClassRule with @RegisterExtension
  - Replace SecurityTestRule with SecurityTestExtension
  - Update static imports from SecurityTestRule to SecurityTest constants
- Migrate JavaSSRFAttackTest to use SecurityHttpClient with ApacheHttpClient4Executor adapter
  - Use Mockito spy on real HttpClient instead of full mock to allow actual HTTP requests
  - Properly verify SSRF protection by capturing and asserting request host
- Add apache.httpclient.version property to parent pom for version consistency

All 9 integration tests now pass successfully.

* chore: Trigger CI pipeline

---------

Signed-off-by: NiklasHerrmann21 <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Daniel Kuntze <[email protected]>

Author: 4 people

.github/workflows/maven-build.yml

@@ -40,12 +40,8 @@ jobs:
         run: mvn -B install --file pom.xml
       - name: Run java-security integration tests
         run: cd java-security-it; mvn -B package --file pom.xml
-      - name: Run spring-xsuaa integration tests
-        run: cd spring-xsuaa-it; mvn -B package --file pom.xml
       - name: Build spring-security-basic-auth
         run: cd samples/spring-security-basic-auth; mvn -B package --file pom.xml
-      - name: Build spring-security-xsuaa-usage
-        run: cd samples/spring-security-xsuaa-usage; mvn -B package --file pom.xml
       - name: Build spring-webflux-security-hybrid-usage
         run: cd samples/spring-webflux-security-hybrid-usage; mvn -B package --file pom.xml
       - name: Build java-security-usage

.gitignore

@@ -43,3 +43,4 @@ __pycache__/
 
 ### Misc ###
 samples/vars.yml
+*.pem

CHANGELOG.md

@@ -1,6 +1,110 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## 4.0.0 - Major Release
+
+This is a major release with breaking changes. The library has been upgraded to Spring Boot 4.x and Jakarta EE 10. For applications still on Spring Boot 3.x, compatibility modules are provided.
+Please check the [4.0 Migration Guide](MIGRATION_4.0.md) for comprehensive upgrade instructions
+
+### :warning: BREAKING CHANGES
+
+#### Spring Boot and Jakarta EE Version Upgrades
+- **Spring Boot**: Upgraded from 3.x to **4.0.3**
+- **Spring Framework**: Upgraded from 6.x to **7.0.5**
+- **Spring Security**: Upgraded from 6.x to **7.0.3**
+- **Jakarta Servlet API**: Upgraded from 6.0.0 to **6.1.0**
+- **Java**: Minimum version remains **Java 17**
+- **JUnit Jupiter**: Upgraded from 5.12.2 to **6.0.3**
+
+#### HTTP Client Default Changed
+**Token-client module** now uses **Java 11's HttpClient** as the default implementation. Apache HttpClient 4 remains available as a dependency for backward compatibility.
+
+**Impact:**
+- ✅ **No code changes required** if you use the default (parameterless) constructors
+- ⚠️ **Deprecated constructors** added for backward compatibility with Apache HttpClient 4
+- ❌ **Will be removed in version 5.0.0** - Plan to migrate to Java HttpClient or custom implementation
+
+**Deprecated in 4.0.0 (Removed in 5.0.0):**
+- `DefaultOAuth2TokenKeyService(CloseableHttpClient)`
+- `DefaultOAuth2TokenService(CloseableHttpClient)`
+- `DefaultOAuth2TokenService(CloseableHttpClient, TokenCacheConfiguration)`
+- `DefaultOidcConfigurationService(CloseableHttpClient)`
+- `HttpClientFactory` interface and `DefaultHttpClientFactory` implementation
+
+**Migration Path:**
+- **Option 1 (Recommended):** Use default constructors - Java 11 HttpClient is used automatically
+- **Option 2 (Temporary):** Continue using deprecated constructors with Apache HttpClient 4
+- **Option 3 (Custom):** Implement `SecurityHttpClientFactory` interface for custom HTTP clients (see [CUSTOM_HTTPCLIENT.md](token-client/CUSTOM_HTTPCLIENT.md))
+
+See the comprehensive [Apache HttpClient Migration Guide](token-client/APACHE_HTTPCLIENT_MIGRATION.md) for detailed migration instructions.
+
+#### Removed Modules
+The following deprecated modules have been removed from the repository:
+
+| Removed Module | Replacement | Migration Guide |
+|---|---|---|
+| `spring-xsuaa` | `spring-security` (Spring Boot 4.x) or `spring-security-3` (Spring Boot 3.x) | [Migration Guide](spring-security/Migration_SpringXsuaaProjects.md) |
+| `spring-xsuaa-starter` | `spring-security-starter` (Spring Boot 4.x) or `spring-security-3-starter` (Spring Boot 3.x) | [Migration Guide](spring-security/Migration_SpringXsuaaProjects.md) |
+| `spring-xsuaa-test` | `java-security-test` | Use JwtGenerator from java-security-test |
+| `spring-security-compatibility` | `spring-security-3` | No changes needed, just switch artifact |
+
+
+### :sparkles: New Features
+
+#### Spring Boot 3.x Compatibility Modules
+For applications that cannot immediately upgrade to Spring Boot 4.x, two new modules provide full compatibility:
+
+**1. spring-security-3** (`com.sap.cloud.security:spring-security-3`)
+- Core security module compatible with Spring Boot 3.5.9, Spring Framework 6.2.15, Spring Security 6.5.7
+- Contains all AutoConfiguration classes and token validation logic
+- Provides Spring Boot 3.x compatibility for applications not yet ready to upgrade to Spring Boot 4.x
+
+**2. resourceserver-security-spring-boot-3-starter** (`com.sap.cloud.security:resourceserver-security-spring-boot-3-starter`)
+- Spring Boot starter for Spring Boot 3.x applications
+- Auto-configures security beans and token validation
+- Same developer experience as the main starter but with Spring Boot 3.x compatibility
+- See [spring-security-3 README](spring-security-3/README.md) for usage
+
+**Migration Path:**
+```xml
+<!-- For Spring Boot 4.x (recommended) -->
+<dependency>
+    <groupId>com.sap.cloud.security</groupId>
+    <artifactId>resourceserver-security-spring-boot-starter</artifactId>
+    <version>4.0.0</version>
+</dependency>
+
+<!-- For Spring Boot 3.x (compatibility layer) -->
+<dependency>
+    <groupId>com.sap.cloud.security</groupId>
+    <artifactId>resourceserver-security-spring-boot-3-starter</artifactId>
+    <version>4.0.0</version>
+</dependency>
+```
+
+**Sample Application:**
+- `samples/spring-webflux-security-hybrid-usage` demonstrates the Spring Boot 3 starter usage
+
+#### Token Client HTTP Client Changes
+- Replaced internal Apache HttpClient implementation with pluggable `SecurityHttpClient` abstraction
+- Default implementation uses Java 11 HttpClient (no external HTTP client library needed)
+- Apache HttpClient 4.5.14 remains as a dependency for backward compatibility
+- `HttpClientFactory` and `DefaultHttpClientFactory` are deprecated but still functional
+- Custom HTTP client implementations can be provided via `SecurityHttpClientFactory` ServiceLoader
+- See [CUSTOM_HTTPCLIENT.md](token-client/CUSTOM_HTTPCLIENT.md) for integration examples (Apache HttpClient 4.x, 5.x, OkHttp, SAP Cloud SDK)
+
+### :package: Dependency Upgrades
+
+Major version bumps:
+- Spring Boot: 3.5.9 → 4.0.3
+- Spring Framework: 6.2.15 → 7.0.5
+- Spring Security: 6.5.7 → 7.0.3
+- Jakarta Servlet API: 6.0.0 → 6.1.0
+- JUnit Jupiter: 5.12.2 → 6.0.3
+- Apache HttpComponents Client: 4.5.14 (unchanged, kept for backward compatibility)
+
+See versions 3.6.x for incremental dependency updates.
+
 ## 3.6.9
 
 - Fix token exchange logic in `DefaultIdTokenExtension` to correctly identify App2App tokens that require exchange (where `aud` contains a single audience different from `azp`)