Spring Boot 如何整合 Digest 认证实现安全登录？

摘要认证是 HTTP 标准中一种基于哈希的挑战应答机制，与基础认证不同，它不会在网络上明文传输密码。在 Spring Boot 应用中，要启用 Digest 认证通常需要借助 Spring Security 的 DigestAuthenticationFilter 或相关配置器。配置过程涉及定义安全规则、设置用户凭据、处理 nonce 有效期以及调整密码存储方式。由于 Digest 认证要求密码在服务端以明文或可逆形式保存，这与传统的 BCrypt 哈希策略存在冲突，因此在设计用户服务时需要特殊处理。本文将从过滤器原理入手，逐步演示完整的 Java 配置类，说明如何自定义 UserDetailsService 返回明文密码，以及如何通过 curl 和浏览器进行验证，并指出该认证方式在现代 Web 应用中的适用场景与局限性。

Digest 认证的底层原理与安全特性

HTTP Digest 认证在 RFC 2617 中定义，它通过 MD5 哈希算法对用户名、密码、nonce 值、请求方法以及 URI 等信息进行组合计算，生成一个摘要值作为响应。服务端收到请求后，会使用预先存储的密码（必须是明文或可恢复的形式）重新计算摘要并与客户端发送的值进行比较，从而验证身份。与 Basic 认证最大的区别在于，密码本身不会出现在网络请求中，只有摘要值会传输，降低了密码被直接截获的风险。

不过 Digest 认证并非没有缺点。MD5 算法已经不再被认为是安全的哈希函数，而且认证过程并不加密请求体，传输的数据依然可能被第三方查看。此外，服务端必须保持密码明文存储或使用可逆加密算法，这削弱了数据库泄露后的密码保护能力。在实际生产环境中，Digest 认证多用于内部系统或老旧客户端兼容场景，新项目更推荐使用 HTTPS 配合表单登录或 OAuth2。

在 Spring Security 中，Digest 认证由 DigestAuthenticationFilter 负责处理。它需要配合 DigestAuthenticationEntryPoint 一起使用，入口点负责在未认证时返回 401 状态码以及 WWW-Authenticate 头，其中包含 realm、nonce、opaque 等参数。客户端收到挑战后，根据这些参数计算摘要并再次发起请求。过滤器和入口点需要共享相同的密钥和 nonce 有效期配置，否则验证会失败。

通过 Java 配置类启用 Spring Security Digest 认证

在 Spring Boot 项目中，首先添加 spring-boot-starter-security 依赖。然后创建一个配置类，继承 WebSecurityConfigurerAdapter 并重写 configure(HttpSecurity http) 方法。使用 http.apply() 方法可以引入 DigestConfigurer 的实例，它简化了过滤器与入口点的装配过程。

以下代码展示了完整的 Java 配置类，其中定义了一个内存用户，密码以明文形式保存在内存中。需要注意的是，Spring Security 默认的用户详情服务要求密码使用 BCrypt 编码，而 Digest 认证需要明文匹配，因此必须使用 NoOpPasswordEncoder 或者自定义密码编码器来绕过哈希。但在实际生产的自定义 UserDetailsService 中，应当通过数据库或其他存储读取明文密码（或可逆加密后的密码），并手动返回 User 对象。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.password.NoOpPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.authentication.www.DigestAuthenticationEntryPoint;
import org.springframework.security.web.authentication.www.DigestAuthenticationFilter;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
                .and()
            .csrf().disable()
            .exceptionHandling()
                .authenticationEntryPoint(digestEntryPoint())
                .and()
            .addFilter(digestAuthenticationFilter());
    }

    @Bean
    public DigestAuthenticationEntryPoint digestEntryPoint() {
        DigestAuthenticationEntryPoint entryPoint = new DigestAuthenticationEntryPoint();
        entryPoint.setRealmName("spring-boot-digest-realm");
        entryPoint.setKey("unique-and-secret-key");
        entryPoint.setNonceValiditySeconds(300);
        return entryPoint;
    }

    @Bean
    public DigestAuthenticationFilter digestAuthenticationFilter() {
        DigestAuthenticationFilter filter = new DigestAuthenticationFilter();
        filter.setUserDetailsService(userDetailsService());
        filter.setAuthenticationEntryPoint(digestEntryPoint());
        return filter;
    }

    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user = User.withUsername("admin")
                .password("admin123")
                .roles("USER")
                .build();
        return new org.springframework.security.core.userdetails.UserDetailsManager() {
            // 简化处理：实际项目中应实现 InMemoryUserDetailsManager 或自定义类
            @Override
            public UserDetails loadUserByUsername(String username) {
                if (username.equals("admin")) {
                    return user;
                }
                throw new UsernameNotFoundException("User not found");
            }
        };
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return NoOpPasswordEncoder.getInstance();
    }
}

上述代码中有一个需要特别注意的地方：User.withUsername() 默认会使用 PasswordEncoder 对密码进行编码。如果我们在创建用户时传入明文密码，而 Spring Security 的 DaoAuthenticationProvider 期望使用 passwordEncoder 来匹配，就会导致异常。为了让 Digest 过滤器能够正常获取明文密码，必须在 UserDetailsService 中返回包含原始密码的 UserDetails 对象，同时将全局的 PasswordEncoder 设置为 NoOpPasswordEncoder。或者更推荐的做法是：不依赖全局密码编码器，而是在 UserDetailsService 中直接构造 User 对象并指定无需编码，但 Spring Security 的 User.withUsername() 总是会返回一个 UserBuilder，它内部会调用 passwordEncoder.encode()，所以最简单的办法是自定义一个 UserDetails 实现类，或者使用 User.withUsername() 后手动设置密码为已编码状态。

另一个容易忽略的细节是 nonce 的有效期。在上面的配置中设置为 300 秒，这意味着客户端在 5 分钟内使用同一个 nonce 发起的请求会被接受。但一旦超时，服务端会重新返回 401 挑战，客户端需要重新计算摘要。这在浏览器中通常由浏览器自动处理，但在使用 curl 或编写自定义 HTTP 客户端时需要逻辑支持。

自定义 UserDetailsService 与密码存储策略

在实际项目中，用户名和密码通常存储在数据库中。Digest 认证要求服务端能够获取明文密码，因为摘要计算需要原始密码参与 MD5 运算。这与目前主流的密码哈希存储（如 BCrypt、Argon2）存在根本矛盾。如果你的数据库已经使用了不可逆哈希存储密码，那么无法支持 Digest 认证，除非改用可逆加密算法（如 AES）对密码进行加密存储，并在用户加载时解密。

下面给出一个基于 JPA 的自定义 UserDetailsService 示例，其中假设用户实体中存储的密码字段是使用 AES 可逆加密后的密文。在加载用户时先解密再构造 UserDetails。注意代码中需要处理密钥管理问题，生产环境建议使用密钥管理服务（KMS）或环境变量注入。

import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class DatabaseUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;
    private final AesEncryptionService encryptionService;

    public DatabaseUserDetailsService(UserRepository userRepository,
                                      AesEncryptionService encryptionService) {
        this.userRepository = userRepository;
        this.encryptionService = encryptionService;
    }

    @Override
    @Transactional(readOnly = true)
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        UserEntity userEntity = userRepository.findByUsername(username)
                .orElseThrow(() -> new UsernameNotFoundException("用户不存在: " + username));
        String plainPassword = encryptionService.decrypt(userEntity.getEncryptedPassword());
        return User.withUsername(userEntity.getUsername())
                .password(plainPassword)
                .roles(userEntity.getRole())
                .build();
    }
}

注意代码中 User.withUsername().password(plainPassword) 依然会触发 PasswordEncoder 的编码逻辑。为了彻底避免这个问题，可以创建一个自定义的 UserDetails 类，直接实现 getPassword() 返回明文，而不使用 User 类的默认构造。或者在配置 DigestAuthenticationFilter 时，不依赖 Spring Security 的 UserDetailsService，而是自己实现 DigestAuthenticationFilter 的 setUserDetailsService 并在服务中返回一个自定义 UserDetails 实现。这里需要根据实际代码结构权衡。

另外需要明确一点：即使使用了可逆加密，数据库泄露时攻击者仍然有可能通过解密算法恢复明文密码，因此必须严格控制加密密钥的访问权限，并定期轮换密钥。对于互联网暴露的服务，强烈建议改用 HTTPS 加表单登录或其他基于令牌的认证方式，而将 Digest 认证限定在受信任的内网环境中。

测试 Digest 认证与常见问题排查

配置完成后，可以使用 curl 命令来测试 Digest 认证流程。首先发送一个不带认证头的请求，服务端会返回 401 状态码以及 WWW-Authenticate: Digest realm="spring-boot-digest-realm", nonce="...", ... 头。然后使用 curl --digest -u admin:admin123 http://localhost:8080/api/secure 命令，curl 会自动处理挑战并携带正确的 Authorization 头，返回预期的响应体。

如果遇到认证失败，最常见的原因是 nonce 过期或密钥不一致。DigestAuthenticationEntryPoint 的 key 用于生成和验证 nonce 签名，如果多个实例或服务节点使用了不同的 key，验证就会失败。在分布式部署中，要确保所有节点共享相同的 key 和 nonce 有效性设置。另一个常见问题是客户端和服务器之间的时钟偏差，由于 nonce 的有效期基于服务器时间，较大的时钟偏移可能导致 nonce 在客户端看来已经过期。

# 第一步：查看 401 挑战信息
curl -v http://localhost:8080/api/secure

# 第二步：使用 --digest 选项自动认证
curl --digest -u admin:admin123 http://localhost:8080/api/secure

# 第三步：手动指定 nonce 和 realm 进行模拟（用于调试）
# 注意：手动计算 Digest 响应较复杂，建议使用 curl 的 --digest 选项

还需要注意浏览器的兼容性表现。现代浏览器（Chrome、Firefox、Edge）都支持 Digest 认证，但用户体验并不友好——浏览器弹出的是原生的对话框，无法自定义样式，而且很多 Web 框架和前端库难以拦截和处理该认证流程。另外，由于 Digest 认证不支持注销机制，浏览器会一直缓存凭据直到会话关闭，这也限制了它在 Web 应用中的使用范围。因此，只建议在 API 调用、内部工具或需要兼容旧客户端的场景中考虑使用 Digest 认证。

最后提醒一下，Spring Security 从 5.7 版本开始逐步废弃了 WebSecurityConfigurerAdapter，推荐使用组件化的 SecurityFilterChain 配置方式。如果使用较新的 Spring Boot 版本，可以相应调整配置代码，将过滤器和入口点以 Bean 的方式注入到 HttpSecurity 中。核心思路保持一致：配置入口点、添加过滤器、提供包含明文密码的用户服务。

Spring BootDigest认证Spring Security修改时间：2026-08-23 00:55:04