fix: prevent endless authentication loops

- docs: document that OkHttp try requests always without Authenticator and when 401 returns, it retries the request with Authenticator

Author: marceljk

CHANGELOG.md

@@ -1,4 +1,6 @@
 ## Release (2025-MM-DD)
+- `core`: [v0.4.1](core/CHANGELOG.md/#v041)
+  - **Bugfix:** Add check in `KeyFlowAuthenticator` to prevent endless loops
 - `objectstorage`: [v0.1.0](services/objectstorage/CHANGELOG.md#v010)
   - Initial onboarding of STACKIT Java SDK for Object storage service
 

core/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.4.1
+- **Bugfix:** Add check in `KeyFlowAuthenticator` to prevent endless loops
+
 ## v0.4.0
 - **Feature:** Added core wait handler structure which can be used by every service waiter implementation.
 

core/src/main/java/cloud/stackit/sdk/core/KeyFlowAuthenticator.java

@@ -52,6 +52,12 @@ public class KeyFlowAuthenticator implements Authenticator {
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * <p>NOTE: It's normal that 2 requests are sent, it's regular OkHttp Authenticator behavior.
+	 * The first request is always attempted without the authenticator and in case the response is
+	 * Unauthorized(=401), OkHttp reattempt the request with the authenticator. See <a
+	 * href="https://square.github.io/okhttp/recipes/#handling-authentication-kt-java">OkHttp
+	 * Docs</a>
+	 *
 	 * @deprecated use constructor with OkHttpClient instead to prevent resource leaks. Will be
 	 *     removed in April 2026.
 	 * @param cfg Configuration to set a custom token endpoint and the token expiration leeway.
@@ -65,6 +71,12 @@ public KeyFlowAuthenticator(CoreConfiguration cfg, ServiceAccountKey saKey) {
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * <p>NOTE: It's normal that 2 requests are sent, it's regular OkHttp Authenticator behavior.
+	 * The first request is always attempted without the authenticator and in case the response is
+	 * Unauthorized(=401), OkHttp reattempt the request with the authenticator. See <a
+	 * href="https://square.github.io/okhttp/recipes/#handling-authentication-kt-java">OkHttp
+	 * Docs</a>
+	 *
 	 * @deprecated use constructor with OkHttpClient instead to prevent resource leaks. Will be
 	 *     removed in April 2026.
 	 * @param cfg Configuration to set a custom token endpoint and the token expiration leeway.
@@ -81,6 +93,12 @@ public KeyFlowAuthenticator(
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * <p>NOTE: It's normal that 2 requests are sent, it's regular OkHttp Authenticator behavior.
+	 * The first request is always attempted without the authenticator and in case the response is
+	 * Unauthorized(=401), OkHttp reattempt the request with the authenticator. See <a
+	 * href="https://square.github.io/okhttp/recipes/#handling-authentication-kt-java">OkHttp
+	 * Docs</a>
+	 *
 	 * @param httpClient OkHttpClient object
 	 * @param cfg Configuration to set a custom token endpoint and the token expiration leeway.
 	 */
@@ -91,6 +109,12 @@ public KeyFlowAuthenticator(OkHttpClient httpClient, CoreConfiguration cfg) thro
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * <p>NOTE: It's normal that 2 requests are sent, it's regular OkHttp Authenticator behavior.
+	 * The first request is always attempted without the authenticator and in case the response is
+	 * Unauthorized(=401), OkHttp reattempt the request with the authenticator. See <a
+	 * href="https://square.github.io/okhttp/recipes/#handling-authentication-kt-java">OkHttp
+	 * Docs</a>
+	 *
 	 * @param httpClient OkHttpClient object
 	 * @param cfg Configuration to set a custom token endpoint and the token expiration leeway.
 	 * @param saKey Service Account Key, which should be used for the authentication
@@ -129,6 +153,9 @@ protected KeyFlowAuthenticator(
 
 	@Override
 	public Request authenticate(Route route, @NotNull Response response) throws IOException {
+		if (response.request().header("Authorization") != null) {
+			return null; // Give up, we've already attempted to authenticate.
+		}
 		String accessToken;
 		try {
 			accessToken = getAccessToken();