Support GSSCredential-based SPNEGO authentication

Signed-off-by: raccoonback <kosb15@naver.com>

Author: raccoonback

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

@@ -750,24 +750,26 @@ SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) provides secure authe
 
 ==== 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.
+. The client sends an HTTP request to a protected resource.
+. The server responds with `401 Unauthorized` and a `WWW-Authenticate: Negotiate` header.
+. The client generates a SPNEGO token based on its Kerberos ticket, and resends the request with an `Authorization: Negotiate <base64-encoded-token>` header.
+. The server validates the token and, if authentication is successful, returns 200 OK.
 
-{examples-link}/spnego/Application.java
+If further negotiation is required, the server may return another 401 with additional data in the `WWW-Authenticate` header.
+
+==== JAAS-based Authenticator
+{examples-link}/spnego/jaas/Application.java
 ----
-include::{examples-dir}/spnego/Application.java[lines=18..39]
+include::{examples-dir}/spnego/jaas/Application.java[lines=18..45]
 ----
 <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. If the server responds with `401 Unauthorized` and includes `WWW-Authenticate: Negotiate`, the client will automatically reauthenticate and retry the request once.
+<5> `SpnegoAuthProvider.Builder` supports the following configuration methods. Please refer to <<spnegoauthprovider-config>>.
+<6> `SpnegoAuthProvider`  generates a SPNEGO token from the Kerberos ticket. It 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
 Specify the path to your JAAS configuration file using the `java.security.auth.login.config` system property.
 
@@ -809,6 +811,75 @@ Specify Kerberos realm and KDC information using the `java.security.krb5.conf` s
 -Djava.security.krb5.conf=/path/to/krb5.conf
 ----
 
+==== GSSCredential-based Authenticator
+For scenarios where you already have a `GSSCredential` available or want to avoid JAAS configuration, you can use `GssCredentialAuthenticator`:
+
+{examples-link}/spnego/gsscredential/Application.java
+----
+include::{examples-dir}/spnego/gsscredential/Application.java[lines=18..46]
+----
+<1> Obtain the `GSSCredential` through other means.
+<2> Configure the GSSCredential-based authenticator for SPNEGO authentication.
+
+This approach is useful when:
+- You want to reuse existing credentials
+- You need more control over credential management
+- JAAS configuration is not available or preferred
+
+==== Custom Authenticator Implementation
+For advanced scenarios where the provided authenticators don't meet your specific requirements, you can implement the `SpnegoAuthenticator` interface directly:
+
+----
+import org.ietf.jgss.GSSContext;
+import reactor.netty.http.client.SpnegoAuthenticator;
+import reactor.netty.http.client.SpnegoAuthProvider;
+
+public class CustomSpnegoAuthenticator implements SpnegoAuthenticator {
+
+    @Override
+    public GSSContext createContext(String serviceName, String remoteHost) throws Exception {
+        // Your custom authentication logic here
+        // This method should return a configured GSSContext
+        // for the specified service and remote host
+        // serviceName: e.g., "HTTP", "LDAP"
+        // remoteHost: target server hostname
+
+        return null; // Replace with actual GSSContext creation logic
+    }
+}
+
+// Usage with advanced configuration
+HttpClient client = HttpClient.create()
+	.spnego(
+		SpnegoAuthProvider.builder(new CustomSpnegoAuthenticator())
+			.serviceName("HTTP")  // Custom service name
+			.unauthorizedStatusCode(401)  // Custom status code
+			.resolveCanonicalHostname(true)  // Use canonical hostname
+			.build()
+	);
+----
+
+This approach is useful when you need:
+- Custom credential acquisition logic
+- Integration with third-party authentication systems
+- Special handling for token caching or refresh
+- Environment-specific authentication flows
+
+[[spnegoauthprovider-config]]
+==== SpnegoAuthProvider Configuration Options
+The `SpnegoAuthProvider.Builder` supports the following configuration Options:
+
+[width="100%",options="header"]
+|=======
+| Method | Default | Description | Example
+| `serviceName(String)` | "HTTP" | Service name for constructing service principal names (serviceName/hostname) | "HTTP", "LDAP"
+| `unauthorizedStatusCode(int)` | 401 | HTTP status code that triggers authentication retry | 401, 407
+| `resolveCanonicalHostname(boolean)` | false | Whether to use canonical hostname resolution via reverse DNS lookup | true for FQDN requirements
+|=======
+
 ==== 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.).
+- If authentication fails, check the server logs and client exception messages, and verify your Kerberos environment settings (realm, KDC, ticket, etc.).
+- `JaasAuthenticator` performs authentication through JAAS login configuration.
+- `GssCredentialAuthenticator` uses pre-existing `GSSCredential` objects, bypassing JAAS configuration.
+- For custom scenarios, implement the `SpnegoAuthenticator` interface to provide your own authentication logic.

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

@@ -0,0 +1,46 @@
+/*
+ * 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.gsscredential;
+
+import org.ietf.jgss.GSSCredential;
+import reactor.netty.http.client.GssCredentialAuthenticator;
+import reactor.netty.http.client.HttpClient;
+import reactor.netty.http.client.SpnegoAuthProvider;
+
+public class Application {
+
+	public static void main(String[] args) {
+		// Assuming you have obtained a GSSCredential from elsewhere
+		GSSCredential credential = obtainGSSCredential(); // <1>
+
+		HttpClient client = HttpClient.create()
+				.spnego(
+						SpnegoAuthProvider.builder(new GssCredentialAuthenticator(credential)) // <2>
+								.build()
+				);
+
+		client.get()
+				.uri("http://protected.example.com/")
+				.responseSingle((res, content) -> content.asString())
+				.block();
+	}
+
+	private static GSSCredential obtainGSSCredential() {
+		// Implement your logic to obtain a GSSCredential
+		// This could involve using a Kerberos library or other means
+		return null;
+	}
+}

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

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package reactor.netty.examples.documentation.http.client.spnego;
+package reactor.netty.examples.documentation.http.client.spnego.jaas;
 
 import reactor.netty.http.client.HttpClient;
 import reactor.netty.http.client.JaasAuthenticator;
@@ -28,8 +28,15 @@ public static void main(String[] args) {
 		System.setProperty("sun.security.krb5.debug", "true"); // <3>
 
 		SpnegoAuthenticator authenticator = new JaasAuthenticator("KerberosLogin"); // <4>
+		SpnegoAuthProvider provider = SpnegoAuthProvider.builder(authenticator)
+				.serviceName("HTTP")
+				.unauthorizedStatusCode(401)
+				.resolveCanonicalHostname(false)
+				.build();
 		HttpClient client = HttpClient.create()
-				.spnego(SpnegoAuthProvider.create(authenticator, 401)); // <5>
+				.spnego(
+						provider // <5>
+				); // <6>
 
 		client.get()
 				.uri("http://protected.example.com/")

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

@@ -0,0 +1,88 @@
+/*
+ * 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 java.util.Objects;
+import org.ietf.jgss.GSSContext;
+import org.ietf.jgss.GSSCredential;
+import org.ietf.jgss.GSSManager;
+import org.ietf.jgss.GSSName;
+import org.ietf.jgss.Oid;
+
+/**
+ * A GSSCredential-based Authenticator implementation for use with SPNEGO providers.
+ * <p>
+ * This authenticator uses a pre-existing GSSCredential to create a GSSContext,
+ * bypassing the need for JAAS login configuration. This is useful when you already
+ * have obtained Kerberos credentials through other means or want more direct control
+ * over the authentication process.
+ * </p>
+ * <p>
+ * The GSSCredential should contain valid Kerberos credentials that can be used
+ * for SPNEGO authentication. The credential's lifetime and validity are managed
+ * externally to this authenticator.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ *     GSSCredential credential = // ... obtain credential
+ *     GssCredentialAuthenticator authenticator = new GssCredentialAuthenticator(credential);
+ *     SpnegoAuthProvider provider = SpnegoAuthProvider.builder(authenticator).build();
+ * </pre>
+ *
+ * @author raccoonback
+ * @since 1.3.0
+ */
+public class GssCredentialAuthenticator implements SpnegoAuthenticator {
+
+	private final GSSCredential credential;
+
+	/**
+	 * Creates a new GssCredentialAuthenticator with the given GSSCredential.
+	 *
+	 * @param credential the GSSCredential to use for authentication
+	 */
+	public GssCredentialAuthenticator(GSSCredential credential) {
+		Objects.requireNonNull(credential, "GSSCredential cannot be null");
+		this.credential = credential;
+	}
+
+	/**
+	 * Creates a GSSContext for the specified service and remote host using the provided GSSCredential.
+	 * <p>
+	 * This method uses the pre-existing GSSCredential to create a GSSContext for SPNEGO
+	 * authentication. The service principal name is constructed as serviceName/remoteHost.
+	 * </p>
+	 *
+	 * @param serviceName the service name (e.g., "HTTP", "FTP")
+	 * @param remoteHost the remote host to authenticate with
+	 * @return the created GSSContext configured for SPNEGO authentication
+	 * @throws Exception if context creation fails
+	 */
+	@Override
+	public GSSContext createContext(String serviceName, String remoteHost) throws Exception {
+		GSSManager manager = GSSManager.getInstance();
+		GSSName serverName = manager.createName(serviceName + "/" + remoteHost, GSSName.NT_HOSTBASED_SERVICE);
+		GSSContext context = manager.createContext(
+				serverName,
+				new Oid("1.3.6.1.5.5.2"),
+				credential,
+				GSSContext.DEFAULT_LIFETIME
+		);
+		context.requestMutualAuth(true);
+		return context;
+	}
+}

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

@@ -15,42 +15,78 @@
  */
 package reactor.netty.http.client;
 
+import java.security.PrivilegedExceptionAction;
 import javax.security.auth.Subject;
 import javax.security.auth.login.LoginContext;
-import javax.security.auth.login.LoginException;
+import org.ietf.jgss.GSSContext;
+import org.ietf.jgss.GSSManager;
+import org.ietf.jgss.GSSName;
+import org.ietf.jgss.Oid;
 
 /**
  * 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.
+ * This authenticator performs a JAAS login using the specified context name and creates a GSSContext
+ * for SPNEGO authentication. It relies on JAAS configuration to obtain Kerberos credentials.
+ * </p>
+ * <p>
+ * The JAAS configuration should define a login context that acquires Kerberos credentials,
+ * typically using the Krb5LoginModule. The login context name provided to this authenticator
+ * must match the entry name in the JAAS configuration file.
  * </p>
  *
+ * <p>Example usage:</p>
+ * <pre>
+ *     JaasAuthenticator authenticator = new JaasAuthenticator("KerberosLogin");
+ *     SpnegoAuthProvider provider = SpnegoAuthProvider.builder(authenticator).build();
+ * </pre>
+ *
  * @author raccoonback
  * @since 1.3.0
  */
 public class JaasAuthenticator implements SpnegoAuthenticator {
 
-	private final String contextName;
+	private final String loginContext;
 
 	/**
 	 * Creates a new JaasAuthenticator with the given context name.
 	 *
-	 * @param contextName the JAAS login context name
+	 * @param loginContext the JAAS login context name
 	 */
-	public JaasAuthenticator(String contextName) {
-		this.contextName = contextName;
+	public JaasAuthenticator(String loginContext) {
+		this.loginContext = loginContext;
 	}
 
 	/**
-	 * Performs a JAAS login using the configured context name and returns the authenticated Subject.
+	 * Creates a GSSContext for the specified service and remote host using JAAS authentication.
+	 * <p>
+	 * This method performs a JAAS login, obtains the authenticated Subject, and creates
+	 * a GSSContext within the Subject's security context. The service principal name
+	 * is constructed as serviceName/remoteHost.
+	 * </p>
 	 *
-	 * @return the authenticated JAAS Subject
-	 * @throws LoginException if login fails
+	 * @param serviceName the service name (e.g., "HTTP", "CIFS")
+	 * @param remoteHost the remote host to authenticate with
+	 * @return the created GSSContext configured for SPNEGO authentication
+	 * @throws Exception if JAAS login or context creation fails
 	 */
 	@Override
-	public Subject login() throws LoginException {
-		LoginContext context = new LoginContext(contextName);
-		context.login();
-		return context.getSubject();
+	public GSSContext createContext(String serviceName, String remoteHost) throws Exception {
+		LoginContext lc = new LoginContext(loginContext);
+		lc.login();
+		Subject subject = lc.getSubject();
+
+		return Subject.doAs(subject, (PrivilegedExceptionAction<GSSContext>) () -> {
+			GSSManager manager = GSSManager.getInstance();
+			GSSName serverName = manager.createName(serviceName + "/" + remoteHost, GSSName.NT_HOSTBASED_SERVICE);
+			GSSContext context = manager.createContext(
+					serverName,
+					new Oid("1.3.6.1.5.5.2"), // SPNEGO
+					null,
+					GSSContext.DEFAULT_LIFETIME
+			);
+			context.requestMutualAuth(true);
+			return context;
+		});
 	}
 }