Spring WebClient NTLM 认证：通过自定义过滤器实现

碧海醫心

发布时间：2025-10-28 10:54:11

776人浏览过

来源于php中文网

原创

spring webclient ntlm 认证：通过自定义过滤器实现

本文详细阐述了如何在 Spring WebClient 中实现 NTLM 认证，解决了原生 WebClient 不支持 NTLM 的问题。核心方案是开发一个自定义的 `ExchangeFilterFunction`，结合 JCIFS 库来处理 NTLM 认证流程，包括 Type 1、Type 2 和 Type 3 消息交换。教程提供了完整的代码示例和集成方法，帮助开发者在 Spring WebFlux 应用中顺利进行 NTLM 认证。

引言：Spring WebClient 与 NTLM 认证的挑战

在企业级应用中，与 Windows 域服务进行交互时，NTLM (NT LAN Manager) 认证是一种常见的挑战。虽然 Spring 的 RestTemplate 结合 Apache HttpClient 可以相对容易地实现 NTLM 认证，但对于基于 Reactor 和 WebFlux 的 WebClient，其内置的认证机制（如 basicAuthentication）并不直接支持 NTLM 协议。这使得许多从 RestTemplate 迁移到 WebClient 的开发者面临如何处理 NTLM 认证的困境。

本文将提供一种在 Spring WebClient 中实现 NTLM 认证的有效方法，通过自定义 ExchangeFilterFunction 并利用 JCIFS 库来处理 NTLM 协议的复杂握手过程。

核心方案：自定义 ExchangeFilterFunction 实现 NTLM 认证

Spring WebClient 提供了强大的扩展机制，其中 ExchangeFilterFunction 允许我们在请求发送前和响应接收后进行拦截和修改。利用这一特性，我们可以构建一个自定义过滤器来封装 NTLM 认证的逻辑。

NTLM 认证是一个多步骤的挑战-响应过程，通常涉及以下三个消息类型：

Type 1 (Negotiate Message)：客户端发送一个不带认证信息的请求，并声明其支持 NTLM。
Type 2 (Challenge Message)：服务器收到 Type 1 消息后，返回一个包含随机挑战码的响应。
Type 3 (Authenticate Message)：客户端使用其凭据和服务器的挑战码生成一个响应，并将其作为认证头发送给服务器。

我们将使用 JCIFS 库来处理 NTLM 消息的生成和解析，因为它提供了对 NTLM 协议的完整支持。

WowTo

用AI建立视频知识库

下载

1. 添加必要的依赖

首先，确保你的项目中包含了 Spring WebFlux 和 JCIFS 库的依赖。


    
    
        org.springframework.boot
        spring-boot-starter-webflux
    

    
    
        eu.agno3.jcifs
        jcifs-ng
        2.1.9 
    

    
    
        io.netty
        netty-handler

2. 创建 NtlmAuthorizedClientExchangeFilterFunction

接下来，我们将实现 ExchangeFilterFunction 接口，并命名为 NtlmAuthorizedClientExchangeFilterFunction。

import jcifs.ntlmssp.NtlmFlags;
import jcifs.ntlmssp.NtlmPasswordAuthentication;
import jcifs.ntlmssp.Type1Message;
import jcifs.ntlmssp.Type2Message;
import jcifs.ntlmssp.Type3Message;
import jcifs.util.Base64;
import org.springframework.http.HttpHeaders;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeFunction;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;

import java.io.IOException;
import java.util.Comparator;
import java.util.List;
import java.util.stream.Collectors;

public final class NtlmAuthorizedClientExchangeFilterFunction implements ExchangeFilterFunction {

    private final NtlmPasswordAuthentication ntlmPasswordAuthentication;
    private final boolean doSigning;
    private final int lmCompatibility;

    /**
     * 构造函数，初始化 NTLM 认证所需的凭据和配置。
     * @param domain 域
     * @param username 用户名
     * @param password 密码
     * @param doSigning 是否启用消息签名
     * @param lmCompatibility LM 兼容性级别 (0-5)
     */
    public NtlmAuthorizedClientExchangeFilterFunction(String domain, String username, String password, boolean doSigning, int lmCompatibility) {
        this.ntlmPasswordAuthentication = new NtlmPasswordAuthentication(domain, username, password);
        this.doSigning = doSigning;
        this.lmCompatibility = lmCompatibility;
        // 设置 JCIFS 的 LM 兼容性级别，影响 NTLMv1/v2 握手
        System.setProperty("jcifs.smb.lmCompatibility", Integer.toString(lmCompatibility));
    }

    @Override
    public Mono filter(final ClientRequest request, final ExchangeFunction next) {
        // NTLM 认证上下文，用于管理认证状态
        NtlmContext ntlmContext = new NtlmContext(ntlmPasswordAuthentication, doSigning, lmCompatibility);

        try {
            // 步骤 1: 发送 Type 1 (Negotiate) 消息
            // 首次请求不带认证头，或者带 Type 1 认证头
            Type1Message type1 = new Type1Message(
                NtlmFlags.NTLMSSP_NEGOTIATE_UNICODE |
                NtlmFlags.NTLMSSP_NEGOTIATE_OEM |
                NtlmFlags.NTLMSSP_REQUEST_TARGET |
                NtlmFlags.NTLMSSP_NEGOTIATE_NTLM |
                NtlmFlags.NTLMSSP_NEGOTIATE_ALWAYS_SIGN |
                NtlmFlags.NTLMSSP_NEGOTIATE_VERSION |
                NtlmFlags.NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY |
                NtlmFlags.NTLMSSP_NEGOTIATE_TARGET_INFO |
                NtlmFlags.NTLMSSP_NEGOTIATE_128 |
                NtlmFlags.NTLMSSP_NEGOTIATE_KEY_EXCH |
                NtlmFlags.NTLMSSP_NEGOTIATE_56,
                ntlmPasswordAuthentication.getDomain(),
                ntlmPasswordAuthentication.getWorkstation()
            );

            String type1Header = "NTLM " + Base64.encode(type1.toByteArray());
            return next.exchange(addNtlmHeader(request, type1Header))
                .publishOn(Schedulers.single()) // 确保请求按顺序处理，维持 HTTP keep-alive
                .flatMap(clientResponse -> {
                    List ntlmAuthHeaders = getNtlmAuthHeaders(clientResponse);
                    if (ntlmAuthHeaders.isEmpty()) {
                        // 如果没有 NTLM 认证头，可能是不需要 NTLM 或服务器不支持
                        // 或者这是一个需要 NTLM 认证但服务器返回了其他错误
                        // 此时可以根据业务需求选择抛出错误或直接返回响应
                        return Mono.just(clientResponse);
                    }
                    String ntlmHeader = ntlmAuthHeaders.get(0); // 获取 Type 2 挑战
                    if (ntlmHeader.length() <= 5) { // "NTLM " 至少5个字符
                        return Mono.error(new IOException("Invalid NTLM challenge header: " + ntlmHeader));
                    }
                    try {
                        byte[] type2Bytes = Base64.decode(ntlmHeader.substring(5));
                        Type2Message type2 = new Type2Message(type2Bytes);

                        // 步骤 2: 接收 Type 2 (Challenge) 消息，并生成 Type 3 (Authenticate) 消息
                        Type3Message type3 = new Type3Message(
                            type1,
                            type2,
                            ntlmPasswordAuthentication.getPassword(),
                            ntlmPasswordAuthentication.getDomain(),
                            ntlmPasswordAuthentication.getUsername(),
                            ntlmPasswordAuthentication.getWorkstation()
                        );

                        String type3Header = "NTLM " + Base64.encode(type3.toByteArray());
                        return next.exchange(addNtlmHeader(request, type3Header)); // 再次发送请求，带 Type 3 认证头
                    } catch (IOException e) {
                        return Mono.error(new IOException("Failed to process NTLM challenge", e));
                    }
                });
        } catch (IOException e) {
            return Mono.error(new IOException("Failed to initialize NTLM authentication", e));
        }
    }

    /**
     * 从响应头中提取 NTLM 认证相关的 WWW-Authenticate 头。
     * @param clientResponse 客户端响应
     * @return 包含 NTLM 认证头的列表
     */
    private static List getNtlmAuthHeaders(ClientResponse clientResponse) {
        List wwwAuthHeaders = clientResponse.headers().header(HttpHeaders.WWW_AUTHENTICATE);
        return wwwAuthHeaders.stream()
            .filter(h -> h.startsWith("NTLM"))
            .sorted(Comparator.comparingInt(String::length)) // 优先处理更长的头（包含挑战信息）
            .collect(Collectors.toList());
    }

    /**
     * 为请求添加 NTLM 认证头。
     * @param clientRequest 原始请求
     * @param ntlmPayload NTLM 认证字符串 (Type 1 或 Type 3)
     * @return 添加了认证头的新请求
     */
    private ClientRequest addNtlmHeader(ClientRequest clientRequest, String ntlmPayload) {
        return ClientRequest.from(clientRequest)
            .header(HttpHeaders.AUTHORIZATION, ntlmPayload)
            .build();
    }

    // 内部类用于管理 NTLM 认证状态，方便在 filter 方法中追踪
    private static class NtlmContext {
        private final NtlmPasswordAuthentication ntlmPasswordAuthentication;
        private final boolean doSigning;
        private final int lmCompatibility;

        public NtlmContext(NtlmPasswordAuthentication ntlmPasswordAuthentication, boolean doSigning, int lmCompatibility) {
            this.ntlmPasswordAuthentication = ntlmPasswordAuthentication;
            this.doSigning = doSigning;
            this.lmCompatibility = lmCompatibility;
        }

        // 可以根据需要添加更多方法来处理 NTLM 状态
    }
}

代码解释：

构造函数：接收域、用户名、密码、是否签名以及 LM 兼容性级别。lmCompatibility 是一个重要的 JCIFS 配置，影响 NTLMv1/v2 握手。通常建议设置为 3 或更高以增强安全性。
filter 方法：
- Type 1 消息发送：首先构建一个 Type1Message (Negotiate Message)，将其编码为 Base64 字符串，并作为 Authorization 头发送。
- 响应处理：flatMap 用于处理第一个请求的响应。如果响应中包含 WWW-Authenticate: NTLM 头（Type 2 消息），则提取挑战信息。
- Type 2 消息解析与 Type 3 消息生成：使用 Type2Message 解析服务器的挑战，然后结合用户凭据生成 Type3Message (Authenticate Message)。
- Type 3 消息发送：将 Type 3 消息编码并再次作为 Authorization 头发送请求。
- publishOn(Schedulers.single())：这一行至关重要。NTLM 认证是一个有状态的协议，通常依赖于 HTTP Keep-Alive 来确保后续的 Type 3 请求在同一个 TCP 连接上发送。Schedulers.single() 确保了对 next.exchange() 的调用是顺序执行的，从而有助于维持连接。
getNtlmAuthHeaders 和 addNtlmHeader：辅助方法，用于从响应头中提取 NTLM 挑战和为请求添加认证头。
错误处理：示例中包含了基本的错误处理，实际应用中应根据需要进行更完善的异常捕获和处理。

3. 将过滤器集成到 WebClient

在创建 WebClient 实例时，通过 filter() 方法将自定义的 NtlmAuthorizedClientExchangeFilterFunction 添加进去。

import org.springframework.web.reactive.function.client.WebClient;

public class NtlmWebClientConfig {

    public WebClient ntlmWebClient() {
        // 替换为你的 NTLM 凭据和配置
        String domain = "YOUR_DOMAIN";
        String username = "YOUR_USERNAME";
        String password = "YOUR_PASSWORD";
        boolean doSigning = true; // 是否启用消息签名，通常建议启用
        int lmCompatibility = 3; // 推荐设置为 3 或更高

        NtlmAuthorizedClientExchangeFilterFunction ntlmFilter =
            new NtlmAuthorizedClientExchangeFilterFunction(domain, username, password, doSigning, lmCompatibility);

        return WebClient.builder()
            .filter(ntlmFilter) // 添加自定义 NTLM 过滤器
            .baseUrl("https://my.ntlm.protected.url.com") // 你的目标服务地址
            .build();
    }

    public static void main(String[] args) {
        NtlmWebClientConfig config = new NtlmWebClientConfig();
        WebClient webClient = config.ntlmWebClient();

        webClient.get()
            .uri("/some/resource")
            .retrieve()
            .bodyToMono(String.class)
            .doOnNext(response -> System.out.println("NTLM 认证成功，响应: " + response))
            .doOnError(error -> System.err.println("NTLM 认证失败或请求错误: " + error.getMessage()))
            .block(); // 在非 WebFlux 应用中用于阻塞等待结果
    }
}

注意事项与限制

JCIFS lmCompatibility 参数：System.setProperty("jcifs.smb.lmCompatibility", Integer.toString(lmCompatibility)); 这一行是全局设置。如果你的应用需要连接到不同 NTLM 配置的服务器，可能需要更精细的控制，例如在每次请求时动态设置或使用线程局部变量。
当前用户上下文认证：原始问题中提到了在 Windows 环境下使用当前用户上下文进行 NTLM 认证，而无需提供用户名和密码。JCIFS 库本身支持通过 JNI 方式获取当前用户凭据，但将其无缝集成到 ExchangeFilterFunction 中会更为复杂，可能需要平台特定的代码或更深层次的集成。本教程提供的方案主要侧重于提供显式凭据的 NTLM 认证。
错误处理：示例代码中的错误处理相对简单。在生产环境中，应考虑更健壮的错误处理机制，例如重试逻辑、详细的日志记录以及区分不同类型的 NTLM 认证失败。
性能考虑：NTLM 认证涉及多次网络往返和计算。对于高并发场景，确保底层 HTTP 客户端（如 Netty）的连接池和 Keep-Alive 机制配置得当非常重要。publishOn(Schedulers.single()) 有助于保持连接，但仍需注意其对并发请求的影响。
安全性：直接在代码中硬编码凭据是不安全的。在实际应用中，应使用配置服务、环境变量或密钥管理系统来安全地存储和获取 NTLM 凭据。

总结

通过实现自定义的 ExchangeFilterFunction 并结合 JCIFS 库，我们成功地为 Spring WebClient 增加了 NTLM 认证的能力。这种方法充分利用了 WebClient 的扩展点，使得开发者能够应对复杂的认证协议，同时保持响应式编程模型的优势。虽然当前用户上下文认证仍是一个挑战，但对于大多数需要显式凭据的 NTLM 场景，上述方案提供了一个清晰且可行的解决方案。

React与Spring集成：构建动态数据查询与展示应用

Java里如何实现在线课堂管理系统_在线课堂管理项目开发方法说明

解决React fetch()请求Spring Boot API时遇到的问题

React Native 实现画中画 (PIP) 模式的完整指南

React Native 中实现画中画 (PIP) 模式的解决方案