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,10 @@ public class KeyFlowAuthenticator implements Authenticator {
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * 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 +69,10 @@ public KeyFlowAuthenticator(CoreConfiguration cfg, ServiceAccountKey saKey) {
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * 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 +89,10 @@ public KeyFlowAuthenticator(
 	/**
 	 * Creates the initial service account and refreshes expired access token.
 	 *
+	 * 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.
 	 */
@@ -89,12 +101,16 @@ public KeyFlowAuthenticator(OkHttpClient httpClient, CoreConfiguration cfg) thro
 	}
 
 	/**
-	 * Creates the initial service account and refreshes expired access token.
-	 *
-	 * @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
-	 */
+     * Creates the initial service account and refreshes expired access token.
+     *
+     * 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
+     */
 	public KeyFlowAuthenticator(
 			OkHttpClient httpClient, CoreConfiguration cfg, ServiceAccountKey saKey) {
 		this(httpClient, cfg, saKey, new EnvironmentVariables());
@@ -129,6 +145,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();