Support SPNEGO (Kerberos) authentication

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

Author: raccoonback

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

@@ -742,3 +742,73 @@ To customize the default settings, you can configure `HttpClient` as follows:
 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
+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.
+
+==== How It Works
+SPNEGO authentication follows this HTTP authentication flow:
+1. The client sends an HTTP request to a protected resource.
+2. The server responds with `401 Unauthorized` and a `WWW-Authenticate: Negotiate` header.
+3. The client generates a SPNEGO token based on its Kerberos ticket, and resends the request with an `Authorization: Negotiate <base64-encoded-token>` header.
+4. The server validates the token and, if authentication is successful, returns 200 OK.
+
+If further negotiation is required, the server may return another 401 with additional data in the WWW-Authenticate header.
+
+{examples-link}/spnego/Application.java
+----
+include::{examples-dir}/spnego/Application.java[lines=18..39]
+----
+<1> Configures the `jaas.conf`. A JAAS configuration file in Java for integrating with authentication backends such as Kerberos.
+<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.
+
+==== Environment Configuration
+===== Example JAAS Configuration
+Specify the path to your JAAS configuration file using the `java.security.auth.login.config` system property.
+
+.`jaas.conf`
+[jaas,conf]
+----
+KerberosLogin {
+    com.sun.security.auth.module.Krb5LoginModule required
+    client=true
+    useKeyTab=true
+    keyTab="/path/to/test.keytab"
+    principal="[email protected]"
+    doNotPrompt=true
+    debug=true;
+};
+----
+
+===== Example Kerberos Configuration
+Specify Kerberos realm and KDC information using the `java.security.krb5.conf` system property.
+
+.`krb5.conf`
+[krb5,conf]
+----
+[libdefaults]
+    default_realm = EXAMPLE.COM
+[realms]
+    EXAMPLE.COM = {
+        kdc = kdc.example.com
+    }
+[domain_realms]
+    .example.com = EXAMPLE.COM
+    example.com = EXAMPLE.COM
+----
+
+===== Configuration Example
+[jvm option]
+----
+-Djava.security.auth.login.config=/path/to/login.conf
+-Djava.security.krb5.conf=/path/to/krb5.conf
+----
+
+==== Notes
+- SPNEGO authentication is fully supported on Java 1.6 and above.
+- If authentication fails, check the server logs and client exception messages, and verify your Kerberos environment settings (realm, KDC, ticket, etc.).

reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/http/client/spnego/Application.java

@@ -0,0 +1,39 @@
+/*
+ * 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.examples.documentation.http.client.spnego;
+
+import reactor.netty.http.client.HttpClient;
+import reactor.netty.http.client.JaasAuthenticator;
+import reactor.netty.http.client.SpnegoAuthProvider;
+import reactor.netty.http.client.SpnegoAuthenticator;
+
+public class Application {
+
+	public static void main(String[] args) {
+		System.setProperty("java.security.auth.login.config", "/path/to/jaas.conf"); // <1>
+		System.setProperty("java.security.krb5.conf", "/path/to/krb5.conf"); // <2>
+		System.setProperty("sun.security.krb5.debug", "true"); // <3>
+
+		SpnegoAuthenticator authenticator = new JaasAuthenticator("KerberosLogin"); // <4>
+		HttpClient client = HttpClient.create()
+				.spnego(SpnegoAuthProvider.create(authenticator)); // <5>
+
+		client.get()
+				.uri("http://protected.example.com/")
+				.responseSingle((res, content) -> content.asString())
+				.block();
+	}
+}

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

@@ -1698,6 +1698,20 @@ public final HttpClient wiretap(boolean enable) {
 		return super.wiretap(enable);
 	}
 
+	/**
+	 * Configure SPNEGO authentication for the HTTP client.
+	 *
+	 * @param spnegoAuthProvider the SPNEGO authentication provider
+	 * @return a new {@link HttpClient}
+	 * @since 1.3.0
+	 */
+	public final HttpClient spnego(SpnegoAuthProvider spnegoAuthProvider) {
+		Objects.requireNonNull(spnegoAuthProvider, "spnegoAuthProvider");
+		HttpClient dup = duplicate();
+		dup.configuration().spnegoAuthProvider = spnegoAuthProvider;
+		return dup;
+	}
+
 	static boolean isCompressing(HttpHeaders h) {
 		return h.contains(HttpHeaderNames.ACCEPT_ENCODING, HttpHeaderValues.GZIP, true)
 				|| h.contains(HttpHeaderNames.ACCEPT_ENCODING, HttpHeaderValues.BR, true);

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

@@ -376,6 +376,7 @@ public WebsocketClientSpec websocketClientSpec() {
 	String uriStr;
 	Function<String, String> uriTagValue;
 	WebsocketClientSpec websocketClientSpec;
+	SpnegoAuthProvider spnegoAuthProvider;
 
 	HttpClientConfig(HttpConnectionProvider connectionProvider, Map<ChannelOption<?>, ?> options,
 			Supplier<? extends SocketAddress> remoteAddress) {
@@ -428,6 +429,7 @@ public WebsocketClientSpec websocketClientSpec() {
 		this.uriStr = parent.uriStr;
 		this.uriTagValue = parent.uriTagValue;
 		this.websocketClientSpec = parent.websocketClientSpec;
+		this.spnegoAuthProvider = parent.spnegoAuthProvider;
 	}
 
 	@Override

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

@@ -489,6 +489,8 @@ static final class HttpClientHandler extends SocketAddress
 		volatile boolean            shouldRetry;
 		volatile HttpHeaders        previousRequestHeaders;
 
+		SpnegoAuthProvider spnegoAuthProvider;
+
 		HttpClientHandler(HttpClientConfig configuration) {
 			this.method = configuration.method;
 			this.followRedirectPredicate = configuration.followRedirectPredicate;
@@ -526,6 +528,7 @@ static final class HttpClientHandler extends SocketAddress
 				this.toURI = uriEndpointFactory.createUriEndpoint(configuration.uri, configuration.websocketClientSpec != null);
 			}
 			this.resourceUrl = toURI.toExternalForm();
+			this.spnegoAuthProvider = configuration.spnegoAuthProvider;
 		}
 
 		@Override
@@ -540,6 +543,19 @@ public SocketAddress get() {
 
 		@SuppressWarnings("ReferenceEquality")
 		Publisher<Void> requestWithBody(HttpClientOperations ch) {
+			if (spnegoAuthProvider != null) {
+				return spnegoAuthProvider.apply(ch, ch.address())
+					.then(
+							Mono.defer(
+									() -> Mono.from(requestWithBodyInternal(ch))
+							)
+					);
+			}
+
+			return requestWithBodyInternal(ch);
+		}
+
+		private Publisher<Void> requestWithBodyInternal(HttpClientOperations ch) {
 			try {
 				ch.resourceUrl = this.resourceUrl;
 				ch.responseTimeout = responseTimeout;

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

@@ -0,0 +1,56 @@
+/*
+ * 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;
+
+import javax.security.auth.Subject;
+import javax.security.auth.login.LoginContext;
+import javax.security.auth.login.LoginException;
+
+/**
+ * A JAAS-based Authenticator implementation for use with SPNEGO providers.
+ * <p>
+ * This authenticator performs a JAAS login using the specified context name and returns the authenticated Subject.
+ * </p>
+ *
+ * @author raccoonback
+ * @since 1.3.0
+ */
+public class JaasAuthenticator implements SpnegoAuthenticator {
+
+	private final String contextName;
+
+	/**
+	 * Creates a new JaasAuthenticator with the given context name.
+	 *
+	 * @param contextName the JAAS login context name
+	 */
+	public JaasAuthenticator(String contextName) {
+		this.contextName = contextName;
+	}
+
+	/**
+	 * Performs a JAAS login using the configured context name and returns the authenticated Subject.
+	 *
+	 * @return the authenticated JAAS Subject
+	 * @throws LoginException if login fails
+	 */
+	@Override
+	public Subject login() throws LoginException {
+		LoginContext context = new LoginContext(contextName);
+		context.login();
+		return context.getSubject();
+	}
+}

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

@@ -0,0 +1,146 @@
+/*
+ * 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;
+
+import static reactor.core.scheduler.Schedulers.boundedElastic;
+
+import io.netty.handler.codec.http.HttpHeaderNames;
+import java.net.InetSocketAddress;
+import java.security.PrivilegedAction;
+import java.util.Base64;
+import javax.security.auth.Subject;
+import javax.security.auth.login.LoginException;
+import org.ietf.jgss.GSSContext;
+import org.ietf.jgss.GSSException;
+import org.ietf.jgss.GSSManager;
+import org.ietf.jgss.GSSName;
+import org.ietf.jgss.Oid;
+import reactor.core.publisher.Mono;
+
+/**
+ * Provides SPNEGO authentication for Reactor Netty HttpClient.
+ * <p>
+ * This provider is responsible for generating and attaching a SPNEGO (Kerberos) token
+ * to the HTTP Authorization header for outgoing requests, enabling single sign-on and
+ * secure authentication in enterprise environments.
+ * </p>
+ *
+ * <p>Typical usage:</p>
+ * <pre>
+ *     HttpClient client = HttpClient.create()
+ *         .spnego(SpnegoAuthProvider.create(new JaasAuthenticator("KerberosLogin")));
+ * </pre>
+ *
+ * @author raccoonback
+ * @since 1.3.0
+ */
+public final class SpnegoAuthProvider {
+
+	private final SpnegoAuthenticator authenticator;
+	private final GSSManager gssManager;
+
+	/**
+	 * Constructs a new SpnegoAuthProvider with the given authenticator and GSSManager.
+	 *
+	 * @param authenticator the authenticator to use for JAAS login
+	 * @param gssManager the GSSManager to use for SPNEGO token generation
+	 */
+	private SpnegoAuthProvider(SpnegoAuthenticator authenticator, GSSManager gssManager) {
+		this.authenticator = authenticator;
+		this.gssManager = gssManager;
+	}
+
+	/**
+	 * Creates a new SPNEGO authentication provider using the default GSSManager instance.
+	 *
+	 * @param authenticator the authenticator to use for JAAS login
+	 * @return a new SPNEGO authentication provider
+	 */
+	public static SpnegoAuthProvider create(SpnegoAuthenticator authenticator) {
+		return create(authenticator, GSSManager.getInstance());
+	}
+
+	/**
+	 * Creates a new SPNEGO authentication provider with a custom GSSManager instance.
+	 * <p>
+	 * This overload is intended for testing or advanced scenarios where a custom GSSManager is needed.
+	 * </p>
+	 *
+	 * @param authenticator the authenticator to use for JAAS login
+	 * @param gssManager the GSSManager to use for SPNEGO token generation
+	 * @return a new SPNEGO authentication provider
+	 */
+	public static SpnegoAuthProvider create(SpnegoAuthenticator authenticator, GSSManager gssManager) {
+		return new SpnegoAuthProvider(authenticator, gssManager);
+	}
+
+	/**
+	 * Applies SPNEGO authentication to the given HTTP client request.
+	 * <p>
+	 * This method generates a SPNEGO token for the specified address and attaches it
+	 * as an Authorization header to the outgoing HTTP request.
+	 * </p>
+	 *
+	 * @param request the HTTP client request to authenticate
+	 * @param address the target server address (used for service principal)
+	 * @return a Mono that completes when the authentication is applied
+	 * @throws RuntimeException if login or token generation fails
+	 */
+	public Mono<Void> apply(HttpClientRequest request, InetSocketAddress address) {
+		return Mono.fromCallable(() -> {
+				try {
+					return Subject.doAs(
+						authenticator.login(),
+						(PrivilegedAction<byte[]>) () -> {
+							try {
+								byte[] token = generateSpnegoToken(address.getHostName());
+								String authHeader = "Negotiate " + Base64.getEncoder().encodeToString(token);
+								request.header(HttpHeaderNames.AUTHORIZATION, authHeader);
+								return token;
+							}
+              catch (GSSException e) {
+								throw new RuntimeException("Failed to generate SPNEGO token", e);
+							}
+						}
+					);
+				}
+        catch (LoginException e) {
+					throw new RuntimeException("Failed to login with SPNEGO", e);
+				}
+			})
+			.subscribeOn(boundedElastic())
+			.then();
+	}
+
+	/**
+	 * Generates a SPNEGO token for the given host name.
+	 * <p>
+	 * This method uses the GSSManager to create a GSSContext and generate a SPNEGO token
+	 * for the specified service principal (HTTP/hostName).
+	 * </p>
+	 *
+	 * @param hostName the target server host name
+	 * @return the raw SPNEGO token bytes
+	 * @throws GSSException if token generation fails
+	 */
+	private byte[] generateSpnegoToken(String hostName) throws GSSException {
+		GSSName serverName = gssManager.createName("HTTP/" + hostName, GSSName.NT_HOSTBASED_SERVICE);
+		Oid spnegoOid = new Oid("1.3.6.1.5.5.2"); // SPNEGO OID
+
+		GSSContext context = gssManager.createContext(serverName, spnegoOid, null, GSSContext.DEFAULT_LIFETIME);
+		return context.initSecContext(new byte[0], 0, 0);
+	}
+}