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.

.../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.

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

raccoonback · 2025-11-20T00:07:55Z

@violetagg
Should this feature also be considered in Http2WebsocketClientOperations and WebsocketClientOperations?
Since redirecting is already handled in those Operations as well, I wanted to check.

violetagg · 2025-11-20T08:35:00Z

@violetagg Should this feature also be considered in Http2WebsocketClientOperations and WebsocketClientOperations? Since redirecting is already handled in those Operations as well, I wanted to check.

yes

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

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

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

…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]>

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

Moved authenticator to occur after the HTTP request is prepared, ensuring configuration is completed before authentication logic runs. Signed-off-by: raccoonback <[email protected]>

Move authentication predicate evaluation from RESPONSE_RECEIVED state to response processing, ensuring all response messages are consumed before retrying with authentication. Signed-off-by: raccoonback <[email protected]>

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

Introduce httpAuthentication(BiFunction) for automatic 401 retry, and rename the predicate-based method to httpAuthenticationWhen for clarity when custom retry conditions are needed. Signed-off-by: raccoonback <[email protected]>

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

reactor-netty-http/src/test/java/reactor/netty/http/client/HttpClientOperationsTest.java

raccoonback · 2025-11-20T15:30:30Z

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

+	/**
+	 * Configure HTTP authentication that retries on 401 Unauthorized responses.
+	 * <p>
+	 * This method provides a generic authentication framework that allows users to implement
+	 * their own authentication mechanisms (e.g., Negotiate/SPNEGO, OAuth, Bearer tokens, custom schemes).
+	 * The framework automatically retries requests when a 401 Unauthorized response is received.
+	 * </p>
+	 *
+	 * <p>Example - Token-based Authentication:</p>
+	 * <pre>
+	 * {@code
+	 * HttpClient client = HttpClient.create()
+	 *     .httpAuthentication(
+	 *         // Add authentication header before request
+	 *         (req, addr) -> {
+	 *             String token = generateAuthToken(addr);
+	 *             req.header(HttpHeaderNames.AUTHORIZATION, "Bearer " + token);
+	 *             return Mono.empty();
+	 *         }
+	 *     );
+	 * }
+	 * </pre>
+	 *
+	 * @param authenticator applies authentication to the request, receives the request and remote address,
+	 *                      returns a Mono that completes when authentication is applied
+	 * @return a new {@link HttpClient}
+	 * @since 1.3.0
+	 * @see #httpAuthenticationWhen(BiPredicate, BiFunction)
+	 */
+	public final HttpClient httpAuthentication(
+			BiFunction<? super HttpClientRequest, ? super SocketAddress, ? extends Mono<Void>> authenticator) {
+		return httpAuthenticationWhen(HttpClientConfig.AUTHENTICATION_PREDICATE, authenticator);
+	}


support HTTP authentication that retries on 401 Unauthorized responses.

I needed to be more concrete - I was thinking about these below. The idea is that if you don't need to delay the token generation (i.e. asking some other component/service for a token) then you can immediately calculate it and add it to the headers thus no need of Mono otherwise you use the variant with Mono. Does this make sense?

public final HttpClient httpAuthentication( BiPredicate<HttpClientRequest, HttpClientResponse> predicate, BiConsumer<? super HttpClientRequest, ? super SocketAddress> authenticator) { } public final HttpClient httpAuthenticationWhen( BiPredicate<HttpClientRequest, HttpClientResponse> predicate, BiFunction<? super HttpClientRequest, ? super SocketAddress, ? extends Mono<Void>> authenticator) { }

@violetagg
Feedback has been applied.
Please review it again. 🙏

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

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

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

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

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

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

raccoonback · 2025-11-20T16:09:54Z

@violetagg
I’ve applied all the review comments.
Please take another look. 🙂

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

This change updates the httpAuthentication() method to require both a retry predicate and an authenticator, allowing users to customize when authentication retry should occur. Signed-off-by: raccoonback <[email protected]>

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

raccoonback added 15 commits November 21, 2025 00:27

Support SPNEGO (Kerberos) authentication

4ddffb0

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

Reuse SPNEGO token until expiry and reset on expiration

6b09c79

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

Ensure GSSContext is disposed after initializing security context

5a8ff02

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

Add SpnegoAuthenticationException for better error handling in SPNEGO…

956b1f8

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

Improve SPNEGO authentication retry mechanism

82dd4f6

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

Support GSSCredential-based SPNEGO authentication

d1ef964

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

Update omitting the stack trace

ee921a0

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

Apply authenticator after HTTP request preparation

e35a028

Moved authenticator to occur after the HTTP request is prepared, ensuring configuration is completed before authentication logic runs. Signed-off-by: raccoonback <[email protected]>

Ensure response messages are drained before authentication retry

0e05222

Move authentication predicate evaluation from RESPONSE_RECEIVED state to response processing, ensuring all response messages are consumed before retrying with authentication. Signed-off-by: raccoonback <[email protected]>

Extend authentication handling to WebSocket operations

1865e7c

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

Add test for HTTP authentication state propagation

721be5c

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

Update documentation and examples for httpAuthentication API changes

dead58f

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

Fix broken test

723ac4b

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

raccoonback force-pushed the issue-3079 branch from 17fbdbe to 723ac4b Compare November 20, 2025 15:28

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

View reviewed changes

reactor-netty-http/src/test/java/reactor/netty/http/client/HttpClientOperationsTest.java Fixed Show fixed Hide fixed

reactor-netty-http/src/test/java/reactor/netty/http/client/HttpClientOperationsTest.java Fixed Show fixed Hide fixed

raccoonback commented Nov 20, 2025

View reviewed changes

Fix checkstyle

d2c310c

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

raccoonback requested a review from violetagg November 20, 2025 16:08

raccoonback added 2 commits November 21, 2025 11:52

Fix test warning log

b65d57d

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

Update httpAuthentication API to accept custom retry predicate

18a038c

This change updates the httpAuthentication() method to require both a retry predicate and an authenticator, allowing users to customize when authentication retry should occur. Signed-off-by: raccoonback <[email protected]>

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!

Check notice

raccoonback commented Nov 17, 2025

Uh oh!

violetagg left a comment

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 Nov 20, 2025

Uh oh!

violetagg commented Nov 20, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

raccoonback commented Jun 23, 2025 •

edited

Loading