Add circuit breaker for OCSP service requests

example/src/main/java/eu/webeid/example/security/AuthTokenDTOAuthenticationProvider.java

@@ -27,6 +27,7 @@
 import eu.webeid.security.challenge.ChallengeNonceStore;
 import eu.webeid.security.exceptions.AuthTokenException;
 import eu.webeid.security.validator.AuthTokenValidator;
+import eu.webeid.security.validator.ValidationInfo;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.security.authentication.AuthenticationProvider;
@@ -72,7 +73,8 @@ public Authentication authenticate(Authentication auth) throws AuthenticationExc
 
         try {
             final String nonce = challengeNonceStore.getAndRemove().getBase64EncodedNonce();
-            final X509Certificate userCertificate = tokenValidator.validate(authToken, nonce);
+            final ValidationInfo validationInfo = tokenValidator.validate(authToken, nonce);
+            final X509Certificate userCertificate = validationInfo.getSubjectCertificate();
             return WebEidAuthentication.fromCertificate(userCertificate, authorities);
         } catch (AuthTokenException e) {
             throw new AuthenticationServiceException("Web eID token validation failed", e);

pom.xml

@@ -16,6 +16,7 @@
         <bouncycastle.version>1.81</bouncycastle.version>
         <jackson.version>2.19.1</jackson.version>
         <slf4j.version>2.0.17</slf4j.version>
+        <resilience4j.version>1.7.0</resilience4j.version>
         <junit-jupiter.version>5.13.3</junit-jupiter.version>
         <assertj.version>3.27.3</assertj.version>
         <mockito.version>5.18.0</mockito.version>
@@ -65,6 +66,29 @@
             <artifactId>bcpkix-jdk18on</artifactId>
             <version>${bouncycastle.version}</version>
         </dependency>
+        <dependency>
+            <groupId>io.github.resilience4j</groupId>
+            <artifactId>resilience4j-all</artifactId>
+            <version>${resilience4j.version}</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>io.github.resilience4j</groupId>
+                    <artifactId>resilience4j-bulkhead</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>io.github.resilience4j</groupId>
+                    <artifactId>resilience4j-cache</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>io.github.resilience4j</groupId>
+                    <artifactId>resilience4j-ratelimiter</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>io.github.resilience4j</groupId>
+                    <artifactId>resilience4j-timelimiter</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>
@@ -90,6 +114,12 @@
             <version>${slf4j.version}</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.awaitility</groupId>
+            <artifactId>awaitility</artifactId>
+            <version>4.3.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

src/main/java/eu/webeid/security/exceptions/UserCertificateOCSPCheckFailedException.java

@@ -22,15 +22,33 @@
 
 package eu.webeid.security.exceptions;
 
+import eu.webeid.security.validator.ocsp.OcspValidationInfo;
+
 /**
  * Thrown when user certificate revocation check with OCSP fails.
  */
 public class UserCertificateOCSPCheckFailedException extends AuthTokenException {
+    private final OcspValidationInfo ocspValidationInfo;
+
     public UserCertificateOCSPCheckFailedException(Throwable cause) {
-        super("User certificate revocation check has failed", cause);
+        this(cause, null);
     }
 
     public UserCertificateOCSPCheckFailedException(String message) {
+        this(message, null);
+    }
+
+    public UserCertificateOCSPCheckFailedException(Throwable cause, OcspValidationInfo ocspValidationInfo) {
+        super("User certificate revocation check has failed", cause);
+        this.ocspValidationInfo = ocspValidationInfo;
+    }
+
+    public UserCertificateOCSPCheckFailedException(String message, OcspValidationInfo ocspValidationInfo) {
         super("User certificate revocation check has failed: " + message);
+        this.ocspValidationInfo = ocspValidationInfo;
+    }
+
+    public OcspValidationInfo getOcspValidationInfo() {
+        return ocspValidationInfo;
     }
 }

src/main/java/eu/webeid/security/exceptions/UserCertificateRevokedException.java

@@ -22,15 +22,25 @@
 
 package eu.webeid.security.exceptions;
 
+import eu.webeid.security.validator.ocsp.OcspValidationInfo;
+
 /**
  * Thrown when the user certificate has been revoked.
  */
 public class UserCertificateRevokedException extends AuthTokenException {
-    public UserCertificateRevokedException() {
+    private final OcspValidationInfo ocspValidationInfo;
+
+    public UserCertificateRevokedException(OcspValidationInfo ocspValidationInfo) {
         super("User certificate has been revoked");
+        this.ocspValidationInfo = ocspValidationInfo;
     }
 
-    public UserCertificateRevokedException(String msg) {
+    public UserCertificateRevokedException(String msg, OcspValidationInfo ocspValidationInfo) {
         super("User certificate has been revoked: " + msg);
+        this.ocspValidationInfo = ocspValidationInfo;
+    }
+
+    public OcspValidationInfo getOcspValidationInfo() {
+        return ocspValidationInfo;
     }
 }

src/main/java/eu/webeid/security/exceptions/UserCertificateUnknownException.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2020-2025 Estonian Information System Authority
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package eu.webeid.security.exceptions;
+
+import eu.webeid.security.validator.ocsp.OcspValidationInfo;
+
+/**
+ * Thrown when the user certificate has been revoked.
+ */
+public class UserCertificateUnknownException extends AuthTokenException {
+    private final OcspValidationInfo ocspValidationInfo;
+
+    public UserCertificateUnknownException(String msg, OcspValidationInfo ocspValidationInfo) {
+        super(msg);
+        this.ocspValidationInfo = ocspValidationInfo;
+    }
+
+    public OcspValidationInfo getOcspValidationInfo() {
+        return ocspValidationInfo;
+    }
+}

src/main/java/eu/webeid/security/validator/AuthTokenValidationConfiguration.java

@@ -24,6 +24,9 @@
 
 import eu.webeid.security.certificate.SubjectCertificatePolicies;
 import eu.webeid.security.validator.ocsp.service.DesignatedOcspServiceConfiguration;
+import eu.webeid.security.validator.ocsp.service.FallbackOcspServiceConfiguration;
+import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
+import io.github.resilience4j.retry.RetryConfig;
 import org.bouncycastle.asn1.ASN1ObjectIdentifier;
 
 import java.net.MalformedURLException;
@@ -50,7 +53,11 @@ public final class AuthTokenValidationConfiguration {
     private Duration ocspRequestTimeout = Duration.ofSeconds(5);
     private Duration allowedOcspResponseTimeSkew = Duration.ofMinutes(15);
     private Duration maxOcspResponseThisUpdateAge = Duration.ofMinutes(2);
+    private boolean rejectUnknownOcspResponseStatus;
     private DesignatedOcspServiceConfiguration designatedOcspServiceConfiguration;
+    private Collection<FallbackOcspServiceConfiguration> fallbackOcspServiceConfigurations = new HashSet<>();
+    private CircuitBreakerConfig circuitBreakerConfig;
+    private RetryConfig circuitBreakerRetryConfig;
     // Don't allow Estonian Mobile-ID policy by default.
     private Collection<ASN1ObjectIdentifier> disallowedSubjectCertificatePolicies = newHashSet(
         SubjectCertificatePolicies.ESTEID_SK_2015_MOBILE_ID_POLICY_V1,
@@ -70,7 +77,11 @@ private AuthTokenValidationConfiguration(AuthTokenValidationConfiguration other)
         this.ocspRequestTimeout = other.ocspRequestTimeout;
         this.allowedOcspResponseTimeSkew = other.allowedOcspResponseTimeSkew;
         this.maxOcspResponseThisUpdateAge = other.maxOcspResponseThisUpdateAge;
+        this.rejectUnknownOcspResponseStatus = other.rejectUnknownOcspResponseStatus;
         this.designatedOcspServiceConfiguration = other.designatedOcspServiceConfiguration;
+        this.fallbackOcspServiceConfigurations = Set.copyOf(other.fallbackOcspServiceConfigurations);
+        this.circuitBreakerConfig = other.circuitBreakerConfig;
+        this.circuitBreakerRetryConfig = other.circuitBreakerRetryConfig;
         this.disallowedSubjectCertificatePolicies = Set.copyOf(other.disallowedSubjectCertificatePolicies);
         this.nonceDisabledOcspUrls = Set.copyOf(other.nonceDisabledOcspUrls);
     }
@@ -135,6 +146,34 @@ public Collection<URI> getNonceDisabledOcspUrls() {
         return nonceDisabledOcspUrls;
     }
 
+    public Collection<FallbackOcspServiceConfiguration> getFallbackOcspServiceConfigurations() {
+        return fallbackOcspServiceConfigurations;
+    }
+
+    public CircuitBreakerConfig getCircuitBreakerConfig() {
+        return circuitBreakerConfig;
+    }
+
+    public void setCircuitBreakerConfig(CircuitBreakerConfig circuitBreakerConfig) {
+        this.circuitBreakerConfig = circuitBreakerConfig;
+    }
+
+    public RetryConfig getCircuitBreakerRetryConfig() {
+        return circuitBreakerRetryConfig;
+    }
+
+    public void setCircuitBreakerRetryConfig(RetryConfig circuitBreakerRetryConfig) {
+        this.circuitBreakerRetryConfig = circuitBreakerRetryConfig;
+    }
+
+    public boolean isRejectUnknownOcspResponseStatus() {
+        return rejectUnknownOcspResponseStatus;
+    }
+
+    public void setRejectUnknownOcspResponseStatus(boolean rejectUnknownOcspResponseStatus) {
+        this.rejectUnknownOcspResponseStatus = rejectUnknownOcspResponseStatus;
+    }
+
     /**
      * Checks that the configuration parameters are valid.
      *
@@ -150,6 +189,7 @@ void validate() {
         requirePositiveDuration(ocspRequestTimeout, "OCSP request timeout");
         requirePositiveDuration(allowedOcspResponseTimeSkew, "Allowed OCSP response time-skew");
         requirePositiveDuration(maxOcspResponseThisUpdateAge, "Max OCSP response thisUpdate age");
+        // TODO: Add OCSP fallback/response validation
     }
 
     AuthTokenValidationConfiguration copy() {

src/main/java/eu/webeid/security/validator/AuthTokenValidator.java

@@ -57,6 +57,6 @@ public interface AuthTokenValidator {
      * @return validated subject certificate
      * @throws AuthTokenException when validation fails
      */
-    X509Certificate validate(WebEidAuthToken authToken, String currentChallengeNonce) throws AuthTokenException;
+    ValidationInfo validate(WebEidAuthToken authToken, String currentChallengeNonce) throws AuthTokenException;
 
 }

src/main/java/eu/webeid/security/validator/AuthTokenValidatorBuilder.java

@@ -26,6 +26,10 @@
 import eu.webeid.security.validator.ocsp.OcspClient;
 import eu.webeid.security.validator.ocsp.OcspClientImpl;
 import eu.webeid.security.validator.ocsp.service.DesignatedOcspServiceConfiguration;
+import eu.webeid.security.validator.ocsp.service.FallbackOcspServiceConfiguration;
+import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
+import io.github.resilience4j.core.IntervalFunction;
+import io.github.resilience4j.retry.RetryConfig;
 import org.bouncycastle.asn1.ASN1ObjectIdentifier;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -187,6 +191,65 @@ public AuthTokenValidatorBuilder withDesignatedOcspServiceConfiguration(Designat
         return this;
     }
 
+    /**
+     * // TODO: Describe the configuration option
+     *
+     * @param serviceConfiguration configurations of the fallback OCSP services
+     * @return the builder instance for method chaining
+     */
+    public AuthTokenValidatorBuilder withFallbackOcspServiceConfiguration(FallbackOcspServiceConfiguration... serviceConfiguration) {
+        // TODO: Validate that no two configurations have the same OCSP service access location
+        Collections.addAll(configuration.getFallbackOcspServiceConfigurations(), serviceConfiguration);
+        LOG.debug("Fallback OCSP services set to {}", configuration.getFallbackOcspServiceConfigurations());
+        return this;
+    }
+
+
+    /**
+     * // TODO: Describe the configuration option
+     *
+     * @param slidingWindowSize
+     * @param minimumNumberOfCalls
+     * @param failureRateThreshold
+     * @param permittedNumberOfCallsInHalfOpenState
+     * @param waitDurationInOpenState
+     * @return the builder instance for method chaining
+     */
+    public AuthTokenValidatorBuilder withCircuitBreakerConfig(int slidingWindowSize, int minimumNumberOfCalls, int failureRateThreshold, int permittedNumberOfCallsInHalfOpenState, Duration waitDurationInOpenState) { // TODO: What do we allow to configure? Use configuration builder.
+        configuration.setCircuitBreakerConfig(CircuitBreakerConfig.custom()
+            .slidingWindowSize(slidingWindowSize)
+            .minimumNumberOfCalls(minimumNumberOfCalls)
+            .failureRateThreshold(failureRateThreshold)
+            .permittedNumberOfCallsInHalfOpenState(permittedNumberOfCallsInHalfOpenState)
+            .waitIntervalFunctionInOpenState(IntervalFunction.of(waitDurationInOpenState))
+            .build());
+        LOG.debug("Using the OCSP circuit breaker configuration");
+        return this;
+    }
+
+    /**
+     * // TODO: Describe the configuration option
+     *
+     * @return the builder instance for method chaining
+     */
+    public AuthTokenValidatorBuilder withCircuitBreakerRetryConfig() { // TODO: What do we allow to configure? Use configuration builder.
+        configuration.setCircuitBreakerRetryConfig(RetryConfig.ofDefaults());
+        LOG.debug("Using the OCSP circuit breaker retry configuration");
+        return this;
+    }
+
+    /**
+     * // TODO: Describe the configuration option
+     *
+     * @param rejectUnknownOcspResponseStatus configures whether only GOOD or REVOKED are accepted as valid OCSP response statuses
+     * @return the builder instance for method chaining
+     */
+    public AuthTokenValidatorBuilder withRejectUnknownOcspResponseStatus(boolean rejectUnknownOcspResponseStatus) {
+        configuration.setRejectUnknownOcspResponseStatus(rejectUnknownOcspResponseStatus);
+        LOG.debug("Using the reject unknown OCSP response status validation configuration");
+        return this;
+    }
+
     /**
      * Uses the provided OCSP client instance during user certificate revocation check with OCSP.
      * The provided client instance must be thread-safe.