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.

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

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.

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

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

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

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 :)

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

raccoonback force-pushed the issue-3079 branch 3 times, most recently from a656f1d to 8dd00a1 Compare June 23, 2025 13:08

Support SPNEGO (Kerberos) authentication

cfa42a3

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

raccoonback force-pushed the issue-3079 branch 2 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 2 times, most recently from 5ce5819 to a6efd89 Compare June 30, 2025 00:04

Reuse SPNEGO token until expiry and reset on expiration

96aa2ba

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

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

raccoonback commented Jul 1, 2025

View reviewed changes

raccoonback added 2 commits July 4, 2025 12:04

Ensure GSSContext is disposed after initializing security context

ecc4095

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

Add SpnegoAuthenticationException for better error handling in SPNEGO…

9a0b4a7

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

raccoonback force-pushed the issue-3079 branch from 0dc9087 to 8fcac3f Compare July 4, 2025 23:57

Improve SPNEGO authentication retry mechanism

a77c0a5

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

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

raccoonback commented Jul 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support SPNEGO Authentication in HttpClient #3813

Support SPNEGO Authentication in HttpClient #3813

raccoonback commented Jun 23, 2025 •

edited

Loading

Uh oh!

raccoonback commented Jun 23, 2025

Uh oh!

raccoonback Jul 1, 2025

Uh oh!

raccoonback Jul 1, 2025

Uh oh!

raccoonback Jul 1, 2025

Uh oh!

raccoonback Jul 1, 2025

Uh oh!

raccoonback Jul 1, 2025

Uh oh!

raccoonback Jul 5, 2025

Uh oh!

raccoonback Jul 5, 2025

Uh oh!

raccoonback commented Jul 5, 2025

Uh oh!

wendigo commented Jul 23, 2025

Uh oh!

Uh oh!

Support SPNEGO Authentication in HttpClient #3813

Are you sure you want to change the base?

Support SPNEGO Authentication in HttpClient #3813

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!

raccoonback Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 5, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback Jul 5, 2025

Choose a reason for hiding this comment

Uh oh!

raccoonback commented Jul 5, 2025

Uh oh!

wendigo commented Jul 23, 2025

Uh oh!

Uh oh!

raccoonback commented Jun 23, 2025 •

edited

Loading