Spring Boot 如何整合 Kerberos 实现 Windows 域免密登录？

Kerberos 协议提供了一种基于票据的身份认证机制，它无需在网络上传输密码，而是通过可信的密钥分发中心（KDC）向客户端和服务端分别发放加密票据。在 Windows 域环境中，域控制器通常承担 KDC 角色，当用户通过域账号登录工作站后，操作系统会自动获取用户的票据授予票据（TGT）。如果企业 Web 应用能够支持 SPNEGO 协议，浏览器就可以将当前用户的 Kerberos 服务票据发送给后端，由后端验证票据并建立会话，从而实现单点登录。Spring Boot 应用要实现这一目标，需要借助 Spring Security Kerberos 扩展，将 SPNEGO 过滤器集成到安全过滤链中。

整合 Spring Boot 与 Kerberos 的过程并不神秘，核心工作集中在三个地方：准备 Kerberos 服务主体和 keytab 文件、配置 Spring Security 的过滤链、以及处理认证成功后的用户信息加载。下面按步骤展开说明。

一、Kerberos 认证流程与整合所需组件

理解 Kerberos 的基本交互有助于排查集成问题。一次典型的 Web 单点登录流程大致如下：客户端浏览器向应用发起请求，应用返回 401 状态码并附带 WWW-Authenticate: Negotiate 响应头；浏览器收到后向 KDC 申请访问该服务主体（Service Principal）的服务票据；然后浏览器再次请求并携带 Authorization: Negotiate 头部，其中包含经过加密的 SPNEGO 令牌；后端过滤器解析并验证该令牌，验证通过后建立安全上下文。

为了完成上述流程，你需要准备两类关键材料。第一类是服务主体名称（Service Principal Name，SPN），通常格式为 HTTP/hostname.domain.com@REALM.COM，其中主机名必须与客户端实际访问的域名一致，否则浏览器会提示找不到服务主体。第二类是 keytab 文件，它保存了服务主体的长期密钥，后端应用使用它来解密和验证服务票据。在 Windows 域环境中，可以使用 ktpass 命令导出 keytab 文件；在 MIT Kerberos 或 Linux 环境中，可以使用 ktab 或 kadmin 生成。

Spring Boot 本身没有类似 @EnableKerberos 的原生注解，因此需要引入 Spring Security Kerberos 扩展模块。该扩展提供了 SpnegoEntryPoint、SpnegoAuthenticationProcessingFilter 和 KerberosAuthenticationProvider 等关键类，配合 Spring Security 的 Java Config 即可完成整合。除了扩展依赖，还需要确保应用服务器支持 GSS-API，不过基于 JDK 的内置实现通常已经足够。

二、Spring Boot 整合 Kerberos 的配置步骤

首先在 Maven 的 pom.xml 中添加两个核心依赖：spring-security-kerberos-web 负责 Web 过滤链集成，spring-security-kerberos-core 提供票据验证和客户端实现。同时还需要添加 spring-security-web 和 spring-security-config，如果使用 Spring Boot，通常直接引入 spring-boot-starter-security 即可。

<dependency>
    <groupId>org.springframework.security.kerberos</groupId>
    <artifactId>spring-security-kerberos-web</artifactId>
    <version>1.0.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.security.kerberos</groupId>
    <artifactId>spring-security-kerberos-core</artifactId>
    <version>1.0.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

接下来准备 keytab 文件和服务主体。假设应用运行在主机 app.internal.com，域名为 INTERNAL.COM，则服务主体应为 HTTP/app.internal.com@INTERNAL.COM。在 Windows 域控上执行类似以下命令导出 keytab：

ktpass /princ HTTP/app.internal.com@INTERNAL.COM /mapuser appsvc /pass * /out C:\keytab\http.keytab /crypto AES256-SHA1 /ptype KRB5_NT_SRV_HST

将生成的 keytab 文件复制到 Spring Boot 应用可读取的位置，例如 C:\keytab\http.keytab。确保运行应用的操作系统账户拥有该文件的读权限，否则在加载密钥时会出现 GSSException: Defective credential detected 之类的错误。

下面是安全配置类的核心代码。需要自定义一个 UserDetailsService，根据票据中的用户名加载用户权限；同时创建 KerberosAuthenticationProvider 并设置票据验证器和用户详情服务。配置类继承 WebSecurityConfigurerAdapter，将 SpnegoAuthenticationProcessingFilter 添加到基础认证过滤器之前。

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Value("${app.service-principal}")
    private String servicePrincipal;

    @Value("${app.keytab-location}")
    private String keytabLocation;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .exceptionHandling()
                .authenticationEntryPoint(spnegoEntryPoint())
                .and()
            .authorizeRequests()
                .antMatchers("/", "/login", "/favicon.ico").permitAll()
                .anyRequest().authenticated()
                .and()
            .addFilterBefore(spnegoAuthenticationProcessingFilter(), BasicAuthenticationFilter.class)
            .csrf().disable();
    }

    @Bean
    public SpnegoEntryPoint spnegoEntryPoint() {
        return new SpnegoEntryPoint("/login");
    }

    @Bean
    public SpnegoAuthenticationProcessingFilter spnegoAuthenticationProcessingFilter() {
        SpnegoAuthenticationProcessingFilter filter = new SpnegoAuthenticationProcessingFilter();
        filter.setAuthenticationManager(authenticationManager());
        return filter;
    }

    @Bean
    public KerberosAuthenticationProvider kerberosAuthenticationProvider() {
        KerberosAuthenticationProvider provider = new KerberosAuthenticationProvider();
        provider.setKerberosClient(new SunJaasKerberosClient());
        provider.setUserDetailsService(userDetailsService());
        return provider;
    }

    @Bean
    public UserDetailsService userDetailsService() {
        return new UserDetailsService() {
            @Override
            public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
                List<GrantedAuthority> authorities = new ArrayList<>();
                authorities.add(new SimpleGrantedAuthority("ROLE_USER"));
                return new User(username, "", authorities);
            }
        };
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.authenticationProvider(kerberosAuthenticationProvider());
    }
}

上述代码中，SpnegoEntryPoint 的构造参数是认证失败后的重定向地址，通常会跳转到一个自定义登录页面或错误提示页。SunJaasKerberosClient 会从系统属性或默认配置中读取 java.security.krb5.conf 指定的 krb5 配置文件，也可以通过代码设置 System.setProperty("java.security.krb5.conf", "C:\\krb5\\krb5.conf") 来明确指定。在实际项目中，建议将 keytab 路径和服务主体提取到 application.properties 中，避免硬编码。

另外，应用还需要一个 krb5.conf 文件，至少指定默认域和 KDC 地址。一个最小配置如下：

[libdefaults]
    default_realm = INTERNAL.COM
    udp_preference_limit = 1

[realms]
    INTERNAL.COM = {
        kdc = dc.internal.com
        admin_server = dc.internal.com
    }

[domain_realm]
    .internal.com = INTERNAL.COM
    internal.com = INTERNAL.COM

将该文件路径通过 JVM 参数或系统属性告知应用。在 Spring Boot 启动类或配置类中，可以在静态块里设置：System.setProperty("java.security.krb5.conf", "C:\\krb5\\krb5.conf");。注意路径中的反斜杠在 Java 字符串中需要转义，如果使用正斜杠也可以。

三、浏览器端配置与常见异常排查

浏览器并不会默认对所有网站启用 Kerberos 集成认证，需要针对站点进行配置。以 Chrome 为例，在 Windows 中可以通过组策略或注册表设置 AuthNegotiateDelegateWhitelist 来添加允许的服务主体后缀，例如 *.internal.com。Firefox 则需要打开 about:config，修改 network.negotiate-auth.trusted-uris 为对应域名。IE 或 Edge 通常在“本地 Intranet”区域中自动启用集成认证，如果应用地址位于 Intranet 区域则无需额外配置。

整合过程中最常见的异常是 GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)，这表示后端应用无法从 keytab 文件获取服务密钥。首先检查 keytab 文件的权限，确保应用进程可读；其次确认文件中的服务主体名称与配置完全一致，包括大小写和域名后缀。另一个高频问题是主机名不匹配，例如浏览器访问的是 IP 地址而不是完整域名，此时 SPNEGO 会失败，需要确保 Service Principal 中的主机名与浏览器地址栏完全一致。

为了定位问题，可以在应用启动时开启 Kerberos 调试输出，在 application.properties 中添加：

logging.level.org.springframework.security=DEBUG
sun.security.krb5.debug=true

其中 sun.security.krb5.debug=true 需要设置为系统属性，而不是 Spring 配置项。可以在启动类中通过 System.setProperty("sun.security.krb5.debug", "true"); 开启。调试信息会输出到控制台，包含票据获取、校验的详细过程，非常有助于快速定位。

四、认证成功后的用户信息与权限扩展

默认的 UserDetailsService 只返回一个固定的 ROLE_USER 权限，这在真实项目中远远不够。你可以在 loadUserByUsername 方法中根据用户名查询数据库或 LDAP，返回包含真实角色的 UserDetails 对象。Kerberos 认证成功后，Spring Security 会将该对象放入 SecurityContext，后续可以通过 SecurityContextHolder.getContext().getAuthentication() 获取当前用户信息，包括用户名和权限集合。

如果需要同时支持 Kerberos 和传统表单登录作为回退方案，可以保留表单登录的配置，并将 SpnegoAuthenticationProcessingFilter 与 UsernamePasswordAuthenticationFilter 共同存在。当浏览器不支持集成认证或协商失败时，用户会被重定向到表单登录页面。这种混合认证模式在企业内网迁移过程中非常实用，既能满足域内用户的免密体验，又能保证外部用户通过账号密码访问。

最后需要提醒的是，keytab 文件等同于服务主体的密码，必须妥善保管。建议将其放置在只有应用账户可访问的目录，并避免提交到版本控制仓库。在容器化部署场景下，可以将 keytab 文件作为 Secret 挂载到 Pod 中，并确保容器内的路径与配置一致。通过合理的密钥管理和安全配置，Spring Boot 与 Kerberos 的整合可以为内网应用带来流畅且安全的单点登录体验。

Spring BootKerberos单点登录修改时间：2026-08-25 11:05:50