Support HTTP 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.

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

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

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

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

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.

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

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

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

raccoonback · 2025-08-24T13:31:22Z

@violetagg
Hello.
I would appreciate it if you could review this PR.
Thanks!

violetagg · 2025-09-01T08:39:26Z

@violetagg Hello. I would appreciate it if you could review this PR. Thanks!

I'm just returning fro vacation, will check it in the next days or so

raccoonback · 2025-10-16T04:26:08Z

@violetagg
Hello.
I would appreciate it if you could review this PR.
Thanks!

violetagg · 2025-10-16T05:41:54Z

I will check this one ... just need to finalise some other tasks.

violetagg · 2025-10-29T13:00:00Z

@raccoonback We discussed to introduce this feature for 1.3.0 version but it is based on 1.2.x branch. Which version are we targeting?

raccoonback · 2025-10-29T13:54:27Z

@violetagg
I think I got confused earlier.
As you mentioned, I’ll make the changes based on version 1.3.x.
ref. #3079 (comment)

raccoonback · 2025-10-29T13:59:40Z

@violetagg
I couldn’t find the 1.3.x branch — would it be okay if I open the PR based on the main branch instead?

violetagg · 2025-10-29T14:06:20Z

@violetagg I couldn’t find the 1.3.x branch — would it be okay if I open the PR based on the main branch instead?

yes main is the branch that is for 1.3.x version

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

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

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

raccoonback · 2025-10-29T15:56:13Z

@violetagg
I’ve changed the target branch to 1.3.x.
Please review PR.

violetagg · 2025-10-31T13:10:25Z

After following the discussion here and having in mind the Reactor Netty API, I think that the solution should be a bit more generic. Also IMO, Reactor Netty is responsible to provide the infrastructure while the user - to provide the concrete implementation (for example how the token will be generated, cached etc).
My proposal is the following (similar to how follow redirect is implemented)

HttpClient.httpAuthentication(
			BiPredicate<HttpClientRequest, HttpClientResponse> authenticationPredicate,
			Consumer<HttpClientRequest> authenticationConsumer)

And the usage will be

HttpClient.create()
			.httpAuthentication(
					(request, response) ->
						return response.status().code() == 401 &&
								response.responseHeaders().contains("WWW-Authenticate", "Negotiate", true)
					,
					request -> {
							String token = getOrGenerateToken(request.resourceUrl());
							request.header("Authorization", "Negotiate " + token);
					}
			);

violetagg · 2025-10-31T13:24:33Z

The API is a bit rough, if we have a delayed token generation we may need the authenticationConsumer to return Mono that we can execute before sending the request. What do you think?

raccoonback · 2025-11-03T09:23:21Z

@violetagg
Thank you for the review. 😀
I have a few questions.

Regarding the token issuance and re-authentication behavior you mentioned — should we let users define only those parts?
Or do you also think users should define the handling of components like GssCredentialAuthenticator?
Currently, the authentication header value is stored and reused for subsequent HTTP requests.
Do you also expect this kind of handling to be managed through user-defined logic?

raccoonback · 2025-11-03T09:25:59Z

@violetagg
I initially considered this as a feature addition specifically for SPNEGO authentication...
However, are you suggesting adding only the authentication flow itself, without including the detailed SPNEGO implementation or dependencies ~~?

violetagg · 2025-11-03T10:11:28Z

@violetagg Thank you for the review. 😀 I have a few questions.

Regarding the token issuance and re-authentication behavior you mentioned — should we let users define only those parts?
Or do you also think users should define the handling of components like GssCredentialAuthenticator?

Currently, the authentication header value is stored and reused for subsequent HTTP requests.
Do you also expect this kind of handling to be managed through user-defined logic?

I would like the user to be responsible for the token generation (thus our API will work not only for SPNEGO) and also the decision how the token will be used/reused, what kind of cache that will be used, what will be the expiration time etc., it is not Reactor Netty decision but user's.

violetagg · 2025-11-03T10:12:33Z

@violetagg I initially considered this as a feature addition specifically for SPNEGO authentication... However, are you suggesting adding only the authentication flow itself, without including the detailed SPNEGO implementation or dependencies ~~?

yes, I understand
however I think that if we try to provide a generic API, later it will be able to be used not only with SPNEGO

We can show case in the examples various http authentications

raccoonback · 2025-11-05T04:17:49Z

@violetagg
I’ll update it according to the direction you suggested.

raccoonback · 2025-11-17T04:22:46Z

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

+				HttpClientOperations operations = connection.as(HttpClientOperations.class);
+				if (operations != null && handler.authenticationPredicate != null) {
+					if (handler.authenticationPredicate.test(operations, operations)) {
+						if (log.isDebugEnabled()) {
+							log.debug(format(operations.channel(), "Authentication predicate matched, triggering retry"));
+						}
+						sink.error(new HttpClientAuthenticationException());
+						return;
+					}
+				}
+


It propagates an exception to trigger a retry, when the authentication requirements are met.

It is better to use the mechanism that we use for follow redirect. reactor.netty.http.client.HttpClientOperations#onInboundNext -> see how "redirecting" is used. The idea is that once we decide to retry we will need to take care of this connection, which means we drain the incoming messages, no message goes to the end user etc (we don't know whether the server will send only the headers or also some message). Basically we need to return to the connection pool a clean connection. Also because we don't send any message to the end user we can switch to auto-read = true

@violetagg I'll check it.

raccoonback · 2025-11-17T04:24:25Z

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

+			if (authenticator != null && authenticationAttempted) {
+				return authenticator.apply(ch, ch.address())
+					.then(
+							Mono.defer(
+									() -> Mono.from(requestWithBodyInternal(ch))
+							)
+					);
+			}
+
+			return requestWithBodyInternal(ch);
+		}


The authenticator is executed first and then the HTTP request is attempted, when a retry is triggered due to HTTP authentication.

Isn't it too early here to provide the HttpClientOperations? HttpClientOperations is still empty and we need to configure it which happens in the new method requestWithBodyInternal.

That makes sense.
I will update it so that the authenticator is applied after the configuration.
Configuration → apply authenticator → request.

raccoonback · 2025-11-17T04:25:13Z

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

+			if (throwable instanceof HttpClientAuthenticationException) {
+				// Set flag to trigger authenticator on retry
+				authenticationAttempted = true;
+				return true;
+			}


The HTTP request is retried, when the HTTP authentication requirements are met.

…ecific design Following the review feedback, this change updates the proposed SPNEGO-specific implementation into a more generic authentication flow that can support various HTTP authentication mechanisms. Signed-off-by: raccoonback <[email protected]>

.../java/reactor/netty/examples/documentation/http/client/authentication/token/Application.java

+	 * Generates an authentication token for the given remote address.
+	 * In a real application, this would retrieve or generate a valid token.
+	 */
+	static String generateAuthToken(SocketAddress remoteAddress) {


raccoonback · 2025-11-17T09:22:14Z

@violetagg
I’ve improved it in the guide you suggested.
Please review it!

violetagg

Thanks! This is the direction. I have some comments related to the implementation.

violetagg · 2025-11-19T07:30:34Z

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

+	 * @return a new {@link HttpClient}
+	 * @since 1.3.0
+	 */
+	public final HttpClient httpAuthentication(


Let's have two APIs (similar to what we have already)

httpAuthentication - this will provide just a BiConsumer

httpAuthenticationWhen - this will use the current signature

@violetagg
Since the decision to apply the authenticator is made using a BiPredicate<HttpClientRequest, HttpClientResponse> predicate, I think that httpAuthentication requires both a BiPredicate and a BiConsumer.
What do you think?

violetagg · 2025-11-19T07:43:33Z

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

+				HttpClientOperations operations = connection.as(HttpClientOperations.class);
+				if (operations != null && handler.authenticationPredicate != null) {
+					if (handler.authenticationPredicate.test(operations, operations)) {
+						if (log.isDebugEnabled()) {
+							log.debug(format(operations.channel(), "Authentication predicate matched, triggering retry"));
+						}
+						sink.error(new HttpClientAuthenticationException());
+						return;
+					}
+				}
+


It is better to use the mechanism that we use for follow redirect. reactor.netty.http.client.HttpClientOperations#onInboundNext -> see how "redirecting" is used. The idea is that once we decide to retry we will need to take care of this connection, which means we drain the incoming messages, no message goes to the end user etc (we don't know whether the server will send only the headers or also some message). Basically we need to return to the connection pool a clean connection. Also because we don't send any message to the end user we can switch to auto-read = true

violetagg · 2025-11-19T07:54:09Z

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

+			if (authenticator != null && authenticationAttempted) {
+				return authenticator.apply(ch, ch.address())
+					.then(
+							Mono.defer(
+									() -> Mono.from(requestWithBodyInternal(ch))
+							)
+					);
+			}
+
+			return requestWithBodyInternal(ch);
+		}


Isn't it too early here to provide the HttpClientOperations? HttpClientOperations is still empty and we need to configure it which happens in the new method requestWithBodyInternal.

violetagg · 2025-11-19T07:57:17Z

...or-netty-http/src/main/java/reactor/netty/http/client/HttpClientAuthenticationException.java

+ * @author Oliver Ko
+ * @since 1.3.0
+ */
+final class HttpClientAuthenticationException extends RuntimeException {


What do you think about omitting the stack trace similar to RedirectClientException?

@violetagg
Okay, I will omit the stack trace!
I have one question: is there a particular reason for omitting the stack trace?

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

reactor-netty-http/src/main/java/reactor/netty/http/client/HttpClientConnect.java Outdated Show resolved Hide resolved

reactor-netty-http/src/main/java/reactor/netty/http/client/HttpClientConnect.java Outdated Show resolved Hide resolved

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

raccoonback commented Jul 31, 2025

View reviewed changes

raccoonback added 6 commits October 29, 2025 23:10

Support SPNEGO (Kerberos) authentication

2d482e1

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

Reuse SPNEGO token until expiry and reset on expiration

2efc75f

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

Ensure GSSContext is disposed after initializing security context

1463e74

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

Add SpnegoAuthenticationException for better error handling in SPNEGO…

3d1d803

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

Improve SPNEGO authentication retry mechanism

7f44121

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

Support GSSCredential-based SPNEGO authentication

5eaf4f0

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

raccoonback force-pushed the issue-3079 branch from b082661 to 5eaf4f0 Compare October 29, 2025 14:15

raccoonback changed the base branch from 1.2.x to main October 29, 2025 14:15

violetagg added this to the 1.3.x Backlog milestone Oct 31, 2025

violetagg linked an issue Oct 31, 2025 that may be closed by this pull request

Support For Spnego Auth scheme support for netty HttpClient similar to Apache's #3079

Open

raccoonback force-pushed the issue-3079 branch from a417bb0 to 31276ce Compare November 17, 2025 04:17

raccoonback commented Nov 17, 2025

View reviewed changes

raccoonback force-pushed the issue-3079 branch from 31276ce to ed6a545 Compare November 17, 2025 04:28

github-advanced-security bot found potential problems Nov 17, 2025

View reviewed changes

raccoonback changed the title ~~Support SPNEGO Authentication in HttpClient~~ Support HTTP Authentication in HttpClient Nov 17, 2025

violetagg requested changes Nov 19, 2025

View reviewed changes

Support HTTP Authentication in HttpClient #3813

Are you sure you want to change the base?

Support HTTP 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

raccoonback commented Aug 24, 2025

Uh oh!

violetagg commented Sep 1, 2025

Uh oh!

raccoonback commented Oct 16, 2025

Uh oh!

violetagg commented Oct 16, 2025

Uh oh!

violetagg commented Oct 29, 2025

Uh oh!

raccoonback commented Oct 29, 2025

Uh oh!

raccoonback commented Oct 29, 2025

Uh oh!

violetagg commented Oct 29, 2025

Uh oh!

raccoonback commented Oct 29, 2025

Uh oh!

violetagg commented Oct 31, 2025

Uh oh!

violetagg commented Oct 31, 2025

Uh oh!

raccoonback commented Nov 3, 2025

Uh oh!

raccoonback commented Nov 3, 2025

Uh oh!

violetagg commented Nov 3, 2025

Uh oh!

violetagg commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

raccoonback commented Nov 5, 2025

raccoonback commented Jun 23, 2025 •

edited

Loading

violetagg commented Nov 3, 2025 •

edited

Loading