Support SPNEGO Authentication in HttpClient #3813

raccoonback · 2025-06-23T11:42:42Z

Motivation

This PR adds support for SPNEGO (Kerberos) authentication to HttpClient, addressing #3079.
SPNEGO is widely used for HTTP authentication in enterprise environments, particularly those based on Kerberos.

Changes

SpnegoAuthProvider

Provides SPNEGO authentication by generating a Kerberos-based token and attaching it to the Authorization header of outgoing HTTP requests.

JaasAuthenticator

Provides a pluggable way to perform JAAS-based Kerberos login, making it easy to integrate with various authentication backends.

HttpClient.spnego(...) API

Adds a new API to configure SPNEGO authentication for HttpClient instances.

HttpClient client = HttpClient.create()
    .spnego(SpnegoAuthProvider.create(new JaasAuthenticator("KerberosLogin")));

client.get()
      .uri("http://protected.example.com/")
      .responseSingle((res, content) -> content.asString())
      .block();

jaas.conf

A JAAS(Java Authentication and Authorization Service) configuration file in Java for integrating with authentication backends such as Kerberos.

KerberosLogin {
    com.sun.security.auth.module.Krb5LoginModule required
    client=true
    useKeyTab=true
    keyTab="/path/to/test.keytab"
    principal="[email protected]"
    doNotPrompt=true
    debug=true;
};

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.

[libdefaults]
    default_realm = EXAMPLE.COM
[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
    }
[domain_realms]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

How It Works

When a server responds with 401 Unauthorized and a WWW-Authenticate: Negotiate header,
the client automatically generates a SPNEGO token using the Kerberos ticket and resends the request with the appropriate Authorization header.
The implementation is based on Java's GSS-API and is compatible with standard Kerberos environments.

Environment Configuration

Requires proper JAAS (jaas.conf) and Kerberos (krb5.conf) configuration.
See the updated documentation for example configuration files and JVM options.

Additional Notes

The SpnegoAuthProvider allows for easy extension and testing by supporting custom authenticators and GSSManager injection.
The feature is fully compatible with Java 1.6+ and works on both Unix and Windows environments.

raccoonback · 2025-06-23T12:10:58Z

I tested Kerberos authentication using the krb5 available at https://formulae.brew.sh/formula/krb5.

raccoonback · 2025-07-01T08:54:21Z

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

+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();
+	}
+}


It logs in using the specified JAAS login context name and returns the authenticated Subject object.

raccoonback · 2025-07-01T09:02:27Z

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

+				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 a SPNEGO authentication expiration response is received via the HTTP response, the authentication header value is cleared.

raccoonback · 2025-07-01T09:03:27Z

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

+			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) {


If SPNEGO authentication is configured through the HttpClient, authentication is attempted before sending the request.

raccoonback · 2025-07-01T09:05:52Z

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

+		if (verifiedAuthHeader != null) {
+			request.header(HttpHeaderNames.AUTHORIZATION, verifiedAuthHeader);
+			return Mono.empty();
+		}


If a valid authentication token already exists, it is reused.

raccoonback · 2025-07-01T09:10:19Z

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

+		return Mono.fromCallable(() -> {
+				try {
+					return Subject.doAs(
+						authenticator.login(),
+						(PrivilegedAction<byte[]>) () -> {
+							try {
+								byte[] token = generateSpnegoToken(address.getHostName());
+								String authHeader = SPNEGO_HEADER + " " + Base64.getEncoder().encodeToString(token);
+
+								verifiedAuthHeader = authHeader;
+								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();


After obtaining Kerberos credentials via JAAS login, a SPNEGO token for the target server is generated using the GSS-API, and the Authorization: Negotiate <token> header is added to the request.

raccoonback · 2025-07-05T04:55:28Z

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

@@ -446,6 +447,16 @@ public Context currentContext() {
 		@Override
 		public void onStateChange(Connection connection, State newState) {
 			if (newState == HttpClientState.RESPONSE_RECEIVED) {
+				HttpClientOperations operations = connection.as(HttpClientOperations.class);
+				if (operations != null && handler.spnegoAuthProvider != null) {
+					if (shouldRetryWithSpnego(operations)) {


Re-authenticates with SPNEGO if necessary.

raccoonback · 2025-07-05T04:56:18Z

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

+			if (throwable instanceof SpnegoRetryException) {
+				return true;
+			}


Configures it to retry even if a SpnegoRetryException occurs.

raccoonback · 2025-07-05T04:57:53Z

@violetagg
Hello!
Please check this PR when you have a chance. 😃

wendigo · 2025-07-23T17:00:45Z

This is so great! Looking forward to get this in :)

wendigo · 2025-07-23T20:09:11Z

I can provide some guidance around APIs and configuration. Not every kerberos-enabled client uses JAAS, therefore the direct Subject/SPNEGO token support should be provided

raccoonback · 2025-07-24T04:29:16Z

@wendigo
Hello!
Thank you for the great point. 😀

I was thinking of allowing users to implement the SpnegoAuthenticator interface, similar to JaasAuthenticator, to support custom authentication logic if needed.

If I understood you correctly, you're suggesting that we should provide a way for users to directly supply a Subject, as in the example below:

public class DirectSubjectAuthenticator implements SpnegoAuthenticator {

    // ...
    private Subject subject;

    @Override
    public Subject login() throws LoginException {
        return subject;
    }

    // ...
}

Would you be able to share a more concrete example or use case?
It would help refine the design in the right direction.

wendigo · 2025-07-24T18:14:56Z

Sure @raccoonback.

I'd like to use reactor-netty in the trino CLI/JDBC/client libraries.

We support delegated/constrained/unconstrained kerberos authentication. Relevant code is here:

https://github.com/trinodb/trino/tree/master/client/trino-client/src/main/java/io/trino/client/auth/kerberos

This is how we add it to the okhttp: https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/auth/kerberos/SpnegoHandler.java

Configurability is important as we expose configuration that allows the user to pass remote service name, service principal name, whether to canonicalize hostname: https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/auth/kerberos/SpnegoHandler.java#L50C5-L54C48

raccoonback · 2025-07-27T15:20:47Z

@violetagg
I think supporting not only JAAS-based authentication but also allowing the user to provide a GSSCredential directly could improve configurability and flexibility.
This would be especially useful in environments where JAAS is not preferred or where credentials need to be managed programmatically.
What do you think about this direction?

cc. @wendigo

violetagg · 2025-07-28T09:28:14Z

I'm currently on vacation. When I return I'll check it. На нд, 27.07.2025 г. в 18:21 KOSEUNGBIN ***@***.***> написа:

…

*raccoonback* left a comment (reactor/reactor-netty#3813) <#3813 (comment)> @violetagg <https://github.com/violetagg> I think supporting not only JAAS-based authentication but also allowing the user to provide a GSSCredential directly could improve configurability and flexibility. This would be especially useful in environments where JAAS is not preferred or where credentials need to be managed programmatically. What do you think about this direction? cc. @wendigo <https://github.com/wendigo> — Reply to this email directly, view it on GitHub <#3813 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFKCVJR2CIDYFH4XV65ZID3KTU6LAVCNFSM6AAAAAB75EX2K6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMRUGQ4DSNBVGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

raccoonback · 2025-07-30T14:49:29Z

@wendigo
I've added GSSCredential-based SPNEGO authentication and support for service name and canonical hostname configuration.
Thank you for the suggestion.

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

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

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

raccoonback · 2025-07-30T23:49:48Z

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

+		private boolean shouldRetryWithSpnego(HttpClientOperations operations) {
+			int statusCode = operations.status().code();
+			HttpHeaders headers = operations.responseHeaders();
+
+			return handler.spnegoAuthProvider.isUnauthorized(statusCode, headers)
+				&& handler.spnegoAuthProvider.canRetry();
+		}


If the resource server responds with a requirement for SPNEGO authentication, the client will retry the authentication.

raccoonback · 2025-07-30T23:53:51Z

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

+		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());
+		}


The previously issued SPNEGO Negotiate Token is cleared, and a reissue attempt is made.

raccoonback · 2025-07-30T23:58:01Z

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

+	@Override
+	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;
+		});
+	}


Authentication is performed based on JAAS.

raccoonback · 2025-07-31T00:02:19Z

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

+	public static final class Builder {
+		private final SpnegoAuthenticator authenticator;
+		private int unauthorizedStatusCode = 401;
+		private String serviceName = "HTTP";
+		private boolean resolveCanonicalHostname;
+
+		private Builder(SpnegoAuthenticator authenticator) {
+			this.authenticator = authenticator;
+		}
+
+		/**
+		 * Sets the HTTP status code that indicates authentication failure.
+		 *
+		 * @param statusCode the status code (default: 401)
+		 * @return this builder
+		 */
+		public Builder unauthorizedStatusCode(int statusCode) {
+			this.unauthorizedStatusCode = statusCode;
+			return this;
+		}
+
+		/**
+		 * Sets the service name for the service principal.
+		 *
+		 * @param serviceName the service name (default: "HTTP")
+		 * @return this builder
+		 */
+		public Builder serviceName(String serviceName) {
+			this.serviceName = serviceName;
+			return this;
+		}
+
+		/**
+		 * Sets whether to resolve canonical hostname.
+		 *
+		 * @param resolveCanonicalHostname true to resolve canonical hostname (default: false)
+		 * @return this builder
+		 */
+		public Builder resolveCanonicalHostname(boolean resolveCanonicalHostname) {
+			this.resolveCanonicalHostname = resolveCanonicalHostname;
+			return this;
+		}
+
+		/**
+		 * Builds the SpnegoAuthProvider instance.
+		 *
+		 * @return a new SpnegoAuthProvider
+		 */
+		public SpnegoAuthProvider build() {
+			return new SpnegoAuthProvider(authenticator, unauthorizedStatusCode, serviceName, resolveCanonicalHostname);
+		}
+	}


The HTTP client receives the options required for SPNEGO authentication:

HTTP status to catch the authentication required error response from the resource server

Service principal name

Whether to handle canonical hostname

raccoonback · 2025-07-31T00:03:28Z

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

+	private String resolveHostName(InetSocketAddress address) {
+		String hostName = address.getHostName();
+		if (resolveCanonicalHostname) {
+			hostName = address.getAddress().getCanonicalHostName();
+		}
+		return hostName;
+	}


It is handled as the canonical hostname.

raccoonback · 2025-07-31T00:03:49Z

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

+	private byte[] generateSpnegoToken(String hostName) throws Exception {
+		if (hostName == null || hostName.trim().isEmpty()) {
+			throw new IllegalArgumentException("Host name cannot be null or empty");
+		}
+
+		GSSContext context = null;
+		try {
+			context = authenticator.createContext(serviceName, hostName.trim());
+			return context.initSecContext(new byte[0], 0, 0);
+		}
+		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);
+					}
+				}
+			}
+		}
+	}


Generates a SPNEGO Negotiate token for the given host name.

raccoonback force-pushed the issue-3079 branch from 7222962 to 9636922 Compare June 23, 2025 11:43

raccoonback force-pushed the issue-3079 branch 5 times, most recently from 19ccf13 to 090e1c2 Compare June 26, 2025 06:49

raccoonback changed the title ~~Support SPNEGO (Kerberos) Authentication in HttpClient~~ Support SPNEGO Authentication in HttpClient Jun 27, 2025

raccoonback force-pushed the issue-3079 branch 3 times, most recently from a6efd89 to 96aa2ba Compare July 1, 2025 08:57

raccoonback commented Jul 1, 2025

View reviewed changes

raccoonback force-pushed the issue-3079 branch 2 times, most recently from 8fcac3f to a77c0a5 Compare July 5, 2025 03:43

raccoonback commented Jul 5, 2025

View reviewed changes

raccoonback force-pushed the issue-3079 branch from 30a337b to 685924c Compare July 30, 2025 15:12

raccoonback added 6 commits July 31, 2025 08:39

Support SPNEGO (Kerberos) authentication

cf051f8

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

Reuse SPNEGO token until expiry and reset on expiration

84e592f

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

Ensure GSSContext is disposed after initializing security context

1d769d2

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

Add SpnegoAuthenticationException for better error handling in SPNEGO…

776de49

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

Improve SPNEGO authentication retry mechanism

f3c5542

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

Support GSSCredential-based SPNEGO authentication

b082661

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

raccoonback force-pushed the issue-3079 branch from 685924c to b082661 Compare July 30, 2025 23:39

raccoonback commented Jul 31, 2025

View reviewed changes

Support SPNEGO Authentication in HttpClient #3813

Are you sure you want to change the base?

Support SPNEGO Authentication in HttpClient #3813

Uh oh!

Conversation

raccoonback commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

SpnegoAuthProvider

JaasAuthenticator

HttpClient.spnego(...) API

jaas.conf

krb5.conf

How It Works

Environment Configuration

Additional Notes

Uh oh!

raccoonback commented Jun 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raccoonback commented Jul 5, 2025

Uh oh!

wendigo commented Jul 23, 2025

Uh oh!

wendigo commented Jul 23, 2025

Uh oh!

raccoonback commented Jul 24, 2025

Uh oh!

wendigo commented Jul 24, 2025

Uh oh!

raccoonback commented Jul 27, 2025

Uh oh!

violetagg commented Jul 28, 2025 via email

Uh oh!

raccoonback commented Jul 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

raccoonback commented Jun 23, 2025 •

edited

Loading