Improve SPNEGO authentication retry mechanism

Signed-off-by: raccoonback <[email protected]>

Author: raccoonback

docs/modules/ROOT/pages/http-client.adoc

@@ -744,7 +744,7 @@ include::{examples-dir}/resolver/Application.java[lines=18..39]
 <1> The timeout of each DNS query performed by this resolver will be 500ms.
 
 [[http-client-spnego]]
-=== SPNEGO (Kerberos) Authentication
+== SPNEGO Authentication
 Reactor Netty HttpClient supports SPNEGO (Kerberos) authentication, which is widely used in enterprise environments.
 SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) provides secure authentication over HTTP using Kerberos.
 
@@ -765,7 +765,7 @@ include::{examples-dir}/spnego/Application.java[lines=18..39]
 <2> Configures the `krb5.conf`. krb5.conf is a Kerberos client configuration file used to define how the client locates and communicates with the Kerberos Key Distribution Center (KDC) for authentication.
 <3> Configures the SPNEGO jaas.conf. A JVM system property that enables detailed debug logging for Kerberos operations in Java.
 <4> `JaasAuthenticator` performs Kerberos authentication using a JAAS configuration (jaas.conf).
-<5> `SpnegoAuthProvider` generates a SPNEGO token from the Kerberos ticket and automatically adds the `Authorization: Negotiate ...` header to HTTP requests.
+<5> `SpnegoAuthProvider` generates a SPNEGO token from the Kerberos ticket and automatically adds the `Authorization: Negotiate ...` header to HTTP requests. If the server responds with `401 Unauthorized` and includes `WWW-Authenticate: Negotiate`, the client will automatically reauthenticate and retry the request once.
 
 ==== Environment Configuration
 ===== Example JAAS Configuration

reactor-netty-http/src/main/java/reactor/netty/http/client/HttpClientConnect.java

@@ -448,11 +448,12 @@ public void onStateChange(Connection connection, State newState) {
 			if (newState == HttpClientState.RESPONSE_RECEIVED) {
 				HttpClientOperations operations = connection.as(HttpClientOperations.class);
 				if (operations != null && handler.spnegoAuthProvider != null) {
-					int statusCode = operations.status().code();
-					HttpHeaders headers = operations.responseHeaders();
-					if (handler.spnegoAuthProvider.isUnauthorized(statusCode, headers)) {
-						handler.spnegoAuthProvider.invalidateCache();
+					if (shouldRetryWithSpnego(operations)) {
+						retryWithSpnego(operations);
+						return;
 					}
+
+					handler.spnegoAuthProvider.resetRetryCount();
 				}
 
 				sink.success(connection);
@@ -468,6 +469,42 @@ public void onStateChange(Connection connection, State newState) {
 				    .subscribe(connection.disposeSubscriber());
 			}
 		}
+
+		/**
+		 * Determines if the current HTTP response requires a SPNEGO authentication retry.
+		 *
+		 * @param operations the HTTP client operations containing the response status and headers
+		 * @return {@code true} if SPNEGO re-authentication should be attempted, {@code false} otherwise
+		 */
+		private boolean shouldRetryWithSpnego(HttpClientOperations operations) {
+			int statusCode = operations.status().code();
+			HttpHeaders headers = operations.responseHeaders();
+
+			return handler.spnegoAuthProvider.isUnauthorized(statusCode, headers)
+				&& handler.spnegoAuthProvider.canRetry();
+		}
+
+		/**
+		 * Triggers a SPNEGO authentication retry by throwing a {@link SpnegoRetryException}.
+		 * <p>
+		 * The exception-based approach ensures that a completely new {@link HttpClientOperations}
+		 * instance is created, avoiding the "Status and headers already sent" error that would
+		 * occur if trying to reuse the existing connection.
+		 * </p>
+		 *
+		 * @param operations the current HTTP client operations that received the 401 response
+		 * @throws SpnegoRetryException always thrown to trigger the retry mechanism
+		 */
+		private void retryWithSpnego(HttpClientOperations operations) {
+			handler.spnegoAuthProvider.invalidateTokenHeader();
+			handler.spnegoAuthProvider.incrementRetryCount();
+
+			if (log.isDebugEnabled()) {
+				log.debug(format(operations.channel(), "Triggering SPNEGO re-authentication"));
+			}
+
+			sink.error(new SpnegoRetryException());
+		}
 	}
 
 	static final class HttpClientHandler extends SocketAddress
@@ -744,6 +781,9 @@ public boolean test(Throwable throwable) {
 				redirect(re.location);
 				return true;
 			}
+			if (throwable instanceof SpnegoRetryException) {
+				return true;
+			}
 			if (shouldRetry && AbortedException.isConnectionReset(throwable)) {
 				shouldRetry = false;
 				redirect(toURI.toString());

reactor-netty-http/src/main/java/reactor/netty/http/client/SpnegoAuthProvider.java

@@ -21,7 +21,10 @@
 import io.netty.handler.codec.http.HttpHeaders;
 import java.net.InetSocketAddress;
 import java.security.PrivilegedAction;
+import java.util.Arrays;
 import java.util.Base64;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
 import javax.security.auth.Subject;
 import javax.security.auth.login.LoginException;
 import org.ietf.jgss.GSSContext;
@@ -30,6 +33,8 @@
 import org.ietf.jgss.GSSName;
 import org.ietf.jgss.Oid;
 import reactor.core.publisher.Mono;
+import reactor.util.Logger;
+import reactor.util.Loggers;
 
 /**
  * Provides SPNEGO authentication for Reactor Netty HttpClient.
@@ -50,14 +55,17 @@
  */
 public final class SpnegoAuthProvider {
 
+	private static final Logger log = Loggers.getLogger(SpnegoAuthProvider.class);
 	private static final String SPNEGO_HEADER = "Negotiate";
 	private static final String STR_OID = "1.3.6.1.5.5.2";
 
 	private final SpnegoAuthenticator authenticator;
 	private final GSSManager gssManager;
 	private final int unauthorizedStatusCode;
 
-	private volatile String verifiedAuthHeader;
+	private final AtomicReference<String> verifiedAuthHeader = new AtomicReference<>();
+	private final AtomicInteger retryCount = new AtomicInteger(0);
+	private static final int MAX_RETRY_COUNT = 1;
 
 	/**
 	 * Constructs a new SpnegoAuthProvider with the given authenticator and GSSManager.
@@ -110,8 +118,9 @@ public static SpnegoAuthProvider create(SpnegoAuthenticator authenticator, GSSMa
 	 * @throws SpnegoAuthenticationException if login or token generation fails
 	 */
 	public Mono<Void> apply(HttpClientRequest request, InetSocketAddress address) {
-		if (verifiedAuthHeader != null) {
-			request.header(HttpHeaderNames.AUTHORIZATION, verifiedAuthHeader);
+		String cachedToken = verifiedAuthHeader.get();
+		if (cachedToken != null) {
+			request.header(HttpHeaderNames.AUTHORIZATION, cachedToken);
 			return Mono.empty();
 		}
 
@@ -124,7 +133,7 @@ public Mono<Void> apply(HttpClientRequest request, InetSocketAddress address) {
 								byte[] token = generateSpnegoToken(address.getHostName());
 								String authHeader = SPNEGO_HEADER + " " + Base64.getEncoder().encodeToString(token);
 
-								verifiedAuthHeader = authHeader;
+								verifiedAuthHeader.set(authHeader);
 								request.header(HttpHeaderNames.AUTHORIZATION, authHeader);
 								return token;
 							}
@@ -154,27 +163,61 @@ public Mono<Void> apply(HttpClientRequest request, InetSocketAddress address) {
 	 * @throws GSSException if token generation fails
 	 */
 	private byte[] generateSpnegoToken(String hostName) throws GSSException {
-		GSSName serverName = gssManager.createName("HTTP/" + hostName, GSSName.NT_HOSTBASED_SERVICE);
+		if (hostName == null || hostName.trim().isEmpty()) {
+			throw new IllegalArgumentException("Host name cannot be null or empty");
+		}
+
+		GSSName serverName = gssManager.createName("HTTP/" + hostName.trim(), GSSName.NT_HOSTBASED_SERVICE);
 		Oid spnegoOid = new Oid(STR_OID); // SPNEGO OID
 
-		GSSContext context = gssManager.createContext(serverName, spnegoOid, null, GSSContext.DEFAULT_LIFETIME);
+		GSSContext context = null;
 		try {
+			context = gssManager.createContext(serverName, spnegoOid, null, GSSContext.DEFAULT_LIFETIME);
 			return context.initSecContext(new byte[0], 0, 0);
-		} finally {
-			context.dispose();
+		}
+		finally {
+			if (context != null) {
+				try {
+					context.dispose();
+				}
+				catch (GSSException e) {
+					// Log but don't propagate disposal errors
+					if (log.isDebugEnabled()) {
+						log.debug("Failed to dispose GSSContext", e);
+					}
+				}
+			}
 		}
 	}
 
 	/**
 	 * Invalidates the cached authentication token.
-	 * <p>
-	 * This method should be called when a response indicates that the current token
-	 * is no longer valid (typically after receiving an unauthorized status code).
-	 * The next request will generate a new authentication token.
-	 * </p>
 	 */
-	public void invalidateCache() {
-		this.verifiedAuthHeader = null;
+	public void invalidateTokenHeader() {
+		this.verifiedAuthHeader.set(null);
+	}
+
+	/**
+	 * Checks if SPNEGO authentication retry is allowed.
+	 *
+	 * @return true if retry is allowed, false otherwise
+	 */
+	public boolean canRetry() {
+		return retryCount.get() < MAX_RETRY_COUNT;
+	}
+
+	/**
+	 * Increments the retry count for SPNEGO authentication attempts.
+	 */
+	public void incrementRetryCount() {
+		retryCount.incrementAndGet();
+	}
+
+	/**
+	 * Resets the retry count for SPNEGO authentication.
+	 */
+	public void resetRetryCount() {
+		retryCount.set(0);
 	}
 
 	/**
@@ -194,6 +237,13 @@ public boolean isUnauthorized(int status, HttpHeaders headers) {
 		}
 
 		String header = headers.get(HttpHeaderNames.WWW_AUTHENTICATE);
-		return header != null && header.startsWith(SPNEGO_HEADER);
+		if (header == null) {
+			return false;
+		}
+
+		// More robust parsing - handle multiple comma-separated authentication schemes
+		return Arrays.stream(header.split(","))
+			.map(String::trim)
+			.anyMatch(auth -> auth.toLowerCase().startsWith(SPNEGO_HEADER.toLowerCase()));
 	}
 }

reactor-netty-http/src/main/java/reactor/netty/http/client/SpnegoAuthenticationException.java

@@ -16,7 +16,7 @@
 package reactor.netty.http.client;
 
 /**
- * Exception thrown when SPNEGO (Kerberos) authentication fails.
+ * Exception thrown when SPNEGO authentication fails.
  *
  * @author raccoonback
  * @since 1.3.0

reactor-netty-http/src/main/java/reactor/netty/http/client/SpnegoRetryException.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025 VMware, Inc. or its affiliates, All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package reactor.netty.http.client;
+
+/**
+ * Exception thrown to trigger a retry when SPNEGO authentication fails with a 401 Unauthorized response.
+ *
+ * @author raccoonback
+ * @since 1.3.0
+ */
+final class SpnegoRetryException extends RuntimeException {
+
+	SpnegoRetryException() {
+		super("SPNEGO authentication requires retry");
+	}
+}