feat: [Connectivity] Introduce OAuth2Option for token cache parameters (SAP#860)

rpanackal · web-flow · commit f0be91aed326 · 2025-07-24T17:44:53.000+02:00
Co-authored-by: Roshin Rajan Panackal &lt;roshin.rajan.panackal@sap.com&gt;
diff --git a/cloudplatform/connectivity-oauth/pom.xml b/cloudplatform/connectivity-oauth/pom.xml
@@ -134,6 +134,10 @@
 			<groupId>org.apache.commons</groupId>
 			<artifactId>commons-lang3</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>com.google.guava</groupId>
+			<artifactId>guava</artifactId>
+		</dependency>
 		<!-- scope "provided" -->
 		<dependency>
 			<groupId>org.projectlombok</groupId>
@@ -192,11 +196,6 @@
 			<artifactId>testutil</artifactId>
 			<scope>test</scope>
 		</dependency>
-		<dependency>
-			<groupId>com.google.guava</groupId>
-			<artifactId>guava</artifactId>
-			<scope>test</scope>
-		</dependency>
 	</dependencies>
 	<build>
 		<plugins>
diff --git a/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/DefaultOAuth2PropertySupplier.java b/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/DefaultOAuth2PropertySupplier.java
@@ -134,6 +134,7 @@ public OAuth2Options getOAuth2Options()
     {
         final OAuth2Options.Builder builder = OAuth2Options.builder();
         options.getOption(OAuth2Options.TokenRetrievalTimeout.class).peek(builder::withTimeLimiter);
+        options.getOption(OAuth2Options.TokenCacheParameters.class).peek(builder::withTokenCacheParameters);
         return builder.build();
     }
 
diff --git a/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2Options.java b/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2Options.java
@@ -8,6 +8,7 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+import com.google.common.annotations.Beta;
 import com.sap.cloud.sdk.cloudplatform.connectivity.ServiceBindingDestinationOptions.OptionsEnhancer;
 import com.sap.cloud.sdk.cloudplatform.resilience.ResilienceConfiguration.TimeLimiterConfiguration;
 
@@ -33,11 +34,23 @@ public final class OAuth2Options
      * @since 5.12.0
      */
     public static final TimeLimiterConfiguration DEFAULT_TIMEOUT = TimeLimiterConfiguration.of(Duration.ofSeconds(10));
+
+    /**
+     * Default token cache configuration used by {@link OAuth2Service}. Effective defaults: 1 hour duration, 1000
+     * entries, 30 seconds delta and cache statistics disabled.
+     *
+     * @see com.sap.cloud.security.xsuaa.tokenflows.TokenCacheConfiguration#DEFAULT
+     * @since 5.21.0
+     */
+    public static final TokenCacheParameters DEFAULT_TOKEN_CACHE_PARAMETERS =
+        TokenCacheParameters.of(Duration.ofHours(1), 1000, Duration.ofSeconds(30));
+
     /**
      * The default {@link OAuth2Options} instance that does not alter the token retrieval process and does not use mTLS
      * for the target system connection.
      */
-    public static final OAuth2Options DEFAULT = new OAuth2Options(false, Map.of(), DEFAULT_TIMEOUT, null);
+    public static final OAuth2Options DEFAULT =
+        new OAuth2Options(false, Map.of(), DEFAULT_TIMEOUT, null, DEFAULT_TOKEN_CACHE_PARAMETERS);
 
     private final boolean skipTokenRetrieval;
     @Nonnull
@@ -58,6 +71,15 @@ public final class OAuth2Options
     @Getter
     private final KeyStore clientKeyStore;
 
+    /**
+     * Configuration for caching OAuth2 tokens.
+     *
+     * @since 5.21.0
+     */
+    @Nonnull
+    @Getter
+    private final TokenCacheParameters tokenCacheParameters;
+
     /**
      * Indicates whether to skip the OAuth2 token flow.
      *
@@ -101,6 +123,7 @@ public static class Builder
         private final Map<String, String> additionalTokenRetrievalParameters = new HashMap<>();
         private KeyStore clientKeyStore;
         private TimeLimiterConfiguration timeLimiter = DEFAULT_TIMEOUT;
+        private TokenCacheParameters tokenCacheParameters = DEFAULT_TOKEN_CACHE_PARAMETERS;
 
         /**
          * Indicates whether to skip the OAuth2 token flow.
@@ -178,6 +201,21 @@ public Builder withTimeLimiter( @Nonnull final TimeLimiterConfiguration timeLimi
             return this;
         }
 
+        /**
+         * Set a custom token cache configuration. {@link #DEFAULT_TOKEN_CACHE_PARAMETERS} by default.
+         *
+         * @param tokenCacheParameters
+         *            The custom token cache parameters.
+         * @return This {@link Builder}.
+         * @since 5.21.0
+         */
+        @Nonnull
+        public Builder withTokenCacheParameters( @Nonnull final TokenCacheParameters tokenCacheParameters )
+        {
+            this.tokenCacheParameters = tokenCacheParameters;
+            return this;
+        }
+
         /**
          * Creates a new {@link OAuth2Options} instance.
          *
@@ -198,7 +236,8 @@ public OAuth2Options build()
                 skipTokenRetrieval,
                 new HashMap<>(additionalTokenRetrievalParameters),
                 timeLimiter,
-                clientKeyStore);
+                clientKeyStore,
+                tokenCacheParameters);
         }
     }
 
@@ -214,4 +253,51 @@ public static class TokenRetrievalTimeout implements OptionsEnhancer<TimeLimiter
         @Nonnull
         private final TimeLimiterConfiguration value;
     }
+
+    /**
+     * Configuration for the token <em>response</em> cache used by {@link OAuth2Service}.
+     *
+     * <p>
+     * <strong>Important:</strong> These values are passed to
+     * {@link com.sap.cloud.security.xsuaa.tokenflows.TokenCacheConfiguration} used by XSUAAs
+     * {@code DefaultOAuth2TokenService}. This cache stores the HTTP token response (including the token) and it governs
+     * the cache entry, <em>not</em> the token's lifetime.
+     *
+     * <p>
+     * Expired (or almost expired) tokens are never served, regardless of {@link #cacheDuration} as xsuaa checks
+     * <code>exp - {@link #tokenExpirationDelta}</code> before returning a cached entry.
+     *
+     * @since 5.21.0
+     */
+    @Beta
+    @Getter
+    @RequiredArgsConstructor( staticName = "of" )
+    public static class TokenCacheParameters implements OptionsEnhancer<TokenCacheParameters>
+    {
+        /**
+         * Upper bound for how long a successful token response may remain cached. A cached entry is ignored earlier if
+         * the token would be (almost) expired.
+         */
+        @Nonnull
+        private final Duration cacheDuration;
+        /**
+         * The maximum number of tokens to cache.
+         */
+        @Nonnull
+        private final Integer cacheSize;
+        /**
+         * The delta to be subtracted from the token expiration time to determine how early should a token be refreshed
+         * before it expires.
+         */
+        @Nonnull
+        private final Duration tokenExpirationDelta;
+
+        @Override
+        @Nonnull
+        public TokenCacheParameters getValue()
+        {
+            return this;
+        }
+    }
+
 }
diff --git a/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2Service.java b/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2Service.java
@@ -3,7 +3,6 @@
 import static com.sap.cloud.security.xsuaa.util.UriUtil.expandPath;
 
 import java.net.URI;
-import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
@@ -19,6 +18,7 @@
 import com.sap.cloud.environment.servicebinding.api.ServiceIdentifier;
 import com.sap.cloud.sdk.cloudplatform.cache.CacheKey;
 import com.sap.cloud.sdk.cloudplatform.cache.CacheManager;
+import com.sap.cloud.sdk.cloudplatform.connectivity.OAuth2Options.TokenCacheParameters;
 import com.sap.cloud.sdk.cloudplatform.connectivity.SecurityLibWorkarounds.ZtisClientIdentity;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationAccessException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationOAuthTokenException;
@@ -91,6 +91,8 @@ class OAuth2Service
     @Nonnull
     @Getter( AccessLevel.PACKAGE )
     private final ResilienceConfiguration resilienceConfiguration;
+    @Nonnull
+    private final TokenCacheParameters tokenCacheParameters;
 
     // package-private for testing
     @Nonnull
@@ -104,7 +106,13 @@ OAuth2TokenService getTokenService( @Nullable final String tenantId )
     private OAuth2TokenService createTokenService( @Nonnull final CacheKey ignored )
     {
         final var tokenCacheConfiguration =
-            TokenCacheConfiguration.getInstance(Duration.ofHours(1), 1000, Duration.ofSeconds(30), false);
+            TokenCacheConfiguration
+                .getInstance(
+                    tokenCacheParameters.getCacheDuration(),
+                    tokenCacheParameters.getCacheSize(),
+                    tokenCacheParameters.getTokenExpirationDelta(),
+                    false); // disable cache statistics
+
         if( !(identity instanceof ZtisClientIdentity) ) {
             return new DefaultOAuth2TokenService(HttpClientFactory.create(identity), tokenCacheConfiguration);
         }
@@ -345,6 +353,7 @@ static class Builder
         private TenantPropagationStrategy tenantPropagationStrategy = TenantPropagationStrategy.ZID_HEADER;
         private final Map<String, String> additionalParameters = new HashMap<>();
         private ResilienceConfiguration.TimeLimiterConfiguration timeLimiter = OAuth2Options.DEFAULT_TIMEOUT;
+        private TokenCacheParameters tokenCacheParameters = OAuth2Options.DEFAULT_TOKEN_CACHE_PARAMETERS;
 
         @Nonnull
         Builder withTokenUri( @Nonnull final String tokenUri )
@@ -422,6 +431,13 @@ Builder withTimeLimiter( @Nonnull final ResilienceConfiguration.TimeLimiterConfi
             return this;
         }
 
+        @Nonnull
+        Builder withTokenCacheParameters( @Nonnull final TokenCacheParameters tokenCacheParameters )
+        {
+            this.tokenCacheParameters = tokenCacheParameters;
+            return this;
+        }
+
         @Nonnull
         OAuth2Service build()
         {
@@ -444,13 +460,15 @@ OAuth2Service build()
 
             // copy the additional parameters to prevent accidental manipulation after the `OAuth2Service` instance has been created.
             final Map<String, String> additionalParameters = new HashMap<>(this.additionalParameters);
+
             return new OAuth2Service(
                 tokenUri,
                 identity,
                 onBehalfOf,
                 tenantPropagationStrategy,
                 additionalParameters,
-                resilienceConfig);
+                resilienceConfig,
+                tokenCacheParameters);
         }
     }
 
diff --git a/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2ServiceBindingDestinationLoader.java b/cloudplatform/connectivity-oauth/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/OAuth2ServiceBindingDestinationLoader.java
@@ -326,6 +326,7 @@ DestinationHeaderProvider createHeaderProvider(
                 .withTenantPropagationStrategyFrom(serviceIdentifier)
                 .withAdditionalParameters(oAuth2Options.getAdditionalTokenRetrievalParameters())
                 .withTimeLimiter(oAuth2Options.getTimeLimiter())
+                .withTokenCacheParameters(oAuth2Options.getTokenCacheParameters())
                 .build();
         return new OAuth2HeaderProvider(oAuth2Service, authHeader);
     }
diff --git a/cloudplatform/connectivity-oauth/src/test/java/com/sap/cloud/sdk/cloudplatform/connectivity/DefaultOAuth2PropertySupplierTest.java b/cloudplatform/connectivity-oauth/src/test/java/com/sap/cloud/sdk/cloudplatform/connectivity/DefaultOAuth2PropertySupplierTest.java
@@ -234,6 +234,29 @@ void testTimeoutConfiguration()
             .isEqualTo(TimeLimiterConfiguration.of(Duration.ofSeconds(100)));
     }
 
+    @Test
+    void testTokenCacheConfigurationOption()
+    {
+        final ServiceBinding binding =
+            new ServiceBindingBuilder(ServiceIdentifier.DESTINATION).with("name", "asdf").build();
+        ServiceBindingDestinationOptions options = ServiceBindingDestinationOptions.forService(binding).build();
+
+        sut = new DefaultOAuth2PropertySupplier(options);
+
+        assertThat(sut.getOAuth2Options().getTokenCacheParameters())
+            .isSameAs(OAuth2Options.DEFAULT_TOKEN_CACHE_PARAMETERS);
+
+        options =
+            ServiceBindingDestinationOptions
+                .forService(binding)
+                .withOption(OAuth2Options.TokenCacheParameters.of(Duration.ofSeconds(10), 5, Duration.ofSeconds(1)))
+                .build();
+        sut = new DefaultOAuth2PropertySupplier(options);
+        assertThat(sut.getOAuth2Options().getTokenCacheParameters())
+            .usingRecursiveComparison()
+            .isEqualTo(OAuth2Options.TokenCacheParameters.of(Duration.ofSeconds(10), 5, Duration.ofSeconds(1)));
+    }
+
     @RequiredArgsConstructor
     private static final class ServiceBindingBuilder
     {
diff --git a/release_notes.md b/release_notes.md
@@ -12,7 +12,7 @@
 
 ### ✨ New Functionality
 
-- 
+- Add `TokenCacheParameters` to `OAuth2Options` to configurate token cache duration, expiration delta and cache size.
 
 ### 📈 Improvements
 

Original file line number	Diff line number	Diff line change
`@@ -134,6 +134,7 @@ public OAuth2Options getOAuth2Options()`
`134`	`134`	`{`
`135`	`135`	`final OAuth2Options.Builder builder = OAuth2Options.builder();`
`136`	`136`	`options.getOption(OAuth2Options.TokenRetrievalTimeout.class).peek(builder::withTimeLimiter);`
	`137`	`+ options.getOption(OAuth2Options.TokenCacheParameters.class).peek(builder::withTokenCacheParameters);`
`137`	`138`	`return builder.build();`
`138`	`139`	`}`
`139`	`140`
Original file line number	Diff line number	Diff line change
`@@ -326,6 +326,7 @@ DestinationHeaderProvider createHeaderProvider(`
`326`	`326`	`.withTenantPropagationStrategyFrom(serviceIdentifier)`
`327`	`327`	`.withAdditionalParameters(oAuth2Options.getAdditionalTokenRetrievalParameters())`
`328`	`328`	`.withTimeLimiter(oAuth2Options.getTimeLimiter())`
	`329`	`+ .withTokenCacheParameters(oAuth2Options.getTokenCacheParameters())`
`329`	`330`	`.build();`
`330`	`331`	`return new OAuth2HeaderProvider(oAuth2Service, authHeader);`
`331`	`332`	`}`