spring-security-3

SAP BTP Spring Security Client Library (Spring Boot 3.x)

Note: This module provides Spring Boot 3.x compatibility. For Spring Boot 4.x, use the spring-security module instead.

This module provides the same API and functionality as spring-security, but is compatible with:

• Spring Boot 3.5.9
• Spring Framework 6.2.15
• Spring Security 6.5.7

Documentation

All documentation from spring-security applies to this module, with the following differences:

Maven Dependencies

Use the Spring Boot 3.x starter instead:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>com.sap.cloud.security</groupId>
    <artifactId>resourceserver-security-spring-boot-3-starter</artifactId>
    <version>4.3.0</version>
</dependency>

HTTP Client

This module uses Apache HttpClient 4.5 for HTTP communication (same as version 3.x of the library).

The main spring-security module (for Spring Boot 4.x) uses Java 11 HttpClient instead.

Samples

Example application using this module:

• Spring Webflux Hybrid Usage - Demonstrates reactive security with Spring Boot 3.x

Migration

This module is a temporary compatibility layer for applications not yet ready to upgrade to Spring Boot 4.x.

Please upgrade to Spring Boot 4.x and the spring-security module as soon as possible.

See MIGRATION_4.0.md for migration instructions.

Distributed Cache Auto-Configuration (since 4.2.0)

By default the library uses an in-memory Caffeine cache for JWKS, OIDC discovery, and outbound tokens — that's the right choice for small services and local development. For larger deployments (many pods, frequent rolling deploys, token-exchange-heavy workloads) we recommend a distributed cache so a restarting pod picks up already-warm entries from its peers. See the top-level README §2.5 for the full recommendation with concrete criteria.

To share the SAP Cloud Security caches across a horizontally-scaled deployment, enable the auto-configuration:

sap:
  security:
    cache:
      distributed:
        enabled: true
        # cache-name: sap-security  # default; override to reuse another cache

Then expose either a SecurityCache<String,String> bean directly or a Spring CacheManager whose cache called sap-security is backed by your distributed store:

import java.time.Duration;
import org.springframework.data.redis.cache.RedisCacheConfiguration;

@Configuration
public class DistributedCacheConfig {
    @Bean
    public CacheManager cacheManager(RedisConnectionFactory rcf) {
        return RedisCacheManager.builder(rcf)
            .initialCacheNames(Set.of("sap-security"))
            .withInitialCacheConfiguration(
                "sap-security",
                RedisCacheConfiguration.defaultCacheConfig()
                    .entryTtl(Duration.ofMinutes(10)))   // must be finite — see main README Warnings
            .build();
    }
}

The auto-config picks that up and wires it into:

• XsuaaTokenFlows — outbound token cache (namespace tokens). Covers client-credentials, refresh-token, and JWT-bearer token-exchange responses (the flow behind DefaultIdTokenExtension / DefaultXsuaaTokenExtension).
• JwtValidatorBuilder (via withSecurityCache) — JWKS and OIDC caches (namespaces jwks, oidc).

Discovery order: (1) user-supplied SecurityCache<String,String> bean → (2) Spring CacheManager.getCache(name). If neither is present the context fails fast — this is on purpose so a misconfigured deployment does not silently run without a shared cache.

For any backend that is not fronted by a Spring CacheManager (raw Redis via Jedis, an in-house store, ...), implement SecurityCache<String,String> directly and declare it as a @Bean — the auto-config prefers it over any CacheManager. Copy-pasteable snippets for Redis (Jedis) and Spring-managed backends live in the top-level Bring your own cache section.

See the top-level README for the complete story including when to use a distributed cache and how to bring your own.

Complete Documentation

For complete documentation on usage, configuration, testing, and troubleshooting, see:

• spring-security README - All documentation applies unless noted above
• MIGRATION_4.0.md - Migration guide from version 3.x to 4.0.1