在Apereo CAS 5.2.x中实现自定义认证处理器的指引 #

我完全理解你从Jasig CAS 3.5.x升级到Apereo CAS 5.2.x时的困惑——旧版本里直接修改deployerConfigContext.xml就能搞定的自定义认证，到了5.x版本因为架构转向Spring Boot自动配置，配置方式确实有了很大变化，而且官方文档里关于构造函数参数的细节确实没讲太细。下面是具体的实现步骤：

1. 自定义认证处理器的实现 #

和3.5.x一样，你依然需要继承AbstractUsernamePasswordAuthenticationHandler，但要注意5.x版本的这个抽象类要求必须通过构造函数传入几个核心依赖，不能再像旧版本那样无参构造了。举个简单的实现例子：

import org.apereo.cas.authentication.*;
import org.apereo.cas.authentication.handler.support.AbstractUsernamePasswordAuthenticationHandler;
import org.apereo.cas.authentication.principal.PrincipalFactory;
import java.util.ArrayList;
import java.util.List;

public class CustomAuthenticationHandler extends AbstractUsernamePasswordAuthenticationHandler {

    // 构造函数必须传入这些参数，父类需要它们完成基础初始化
    public CustomAuthenticationHandler(String name, 
                                       PrincipalNameTransformer principalNameTransformer,
                                       PasswordEncoder passwordEncoder,
                                       List<CredentialMetaDataPopulator> metaDataPopulators) {
        super(name, principalNameTransformer, passwordEncoder, metaDataPopulators);
    }

    @Override
    protected HandlerResult authenticateUsernamePasswordInternal(UsernamePasswordCredential credential, String originalPassword) 
            throws GeneralSecurityException, PreventedException {
        
        // 这里写你的自定义认证逻辑：比如查询数据库、调用第三方验证接口等
        String username = credential.getUsername();
        String password = credential.getPassword();

        // 示例：简单的硬编码验证，实际替换为你的业务逻辑
        if ("testuser".equals(username) && "testpass".equals(password)) {
            // 构造认证成功的返回结果
            return createHandlerResult(credential, getPrincipalFactory().createPrincipal(username), null);
        }
        
        // 验证失败抛出异常
        throw new FailedLoginException("Invalid username or password");
    }
}

2. 注册自定义处理器到CAS认证流程 #

CAS 5.x不再通过XML注册Bean，而是用Java配置类将自定义处理器加入到认证执行计划中。创建一个配置类：

import org.apereo.cas.authentication.AuthenticationEventExecutionPlan;
import org.apereo.cas.authentication.AuthenticationEventExecutionPlanConfigurer;
import org.apereo.cas.authentication.AuthenticationHandler;
import org.apereo.cas.authentication.principal.PrincipalNameTransformer;
import org.apereo.cas.configuration.CasConfigurationProperties;
import org.apereo.cas.util.password.PasswordEncoder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.ArrayList;

@Configuration
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class CustomAuthConfiguration implements AuthenticationEventExecutionPlanConfigurer {

    // 注入CAS默认提供的依赖
    @Autowired
    private PasswordEncoder passwordEncoder;

    @Autowired
    private PrincipalNameTransformer principalNameTransformer;

    @Override
    public void configureAuthenticationExecutionPlan(AuthenticationEventExecutionPlan plan) {
        // 将自定义处理器注册到认证计划中
        plan.registerAuthenticationHandler(customAuthenticationHandler());
    }

    @Bean
    public AuthenticationHandler customAuthenticationHandler() {
        // 实例化自定义处理器，传入构造函数所需的参数
        return new CustomAuthenticationHandler(
                "CustomAuthHandler", // 处理器的唯一标识，可自定义
                principalNameTransformer, // 用户名转换器，默认不做转换
                passwordEncoder, // 密码加密器，CAS默认提供多种实现
                new ArrayList<>() // 元数据填充器，不需要的话传空列表即可
        );
    }
}

3. 构造函数参数说明 #

这里重点解释一下你关心的构造函数参数：

• name：自定义处理器的唯一名称，用于日志和标识，随便取一个有意义的名字就行
• principalNameTransformer：用于对用户名进行预处理（比如统一转小写/大写），CAS默认提供NoOpPrincipalNameTransformer（不做任何转换），你也可以自定义实现
• passwordEncoder：密码加密器，CAS默认支持BCrypt、SHA等多种加密方式，如果你不需要加密可以用PlainTextPasswordEncoder
• metaDataPopulators：用于填充认证相关的元数据，一般场景下不需要，传空列表即可

4. 额外提示 #

• 如果你的自定义处理器需要读取配置文件中的参数，可以通过@ConfigurationProperties注解注入，或者在配置类中读取CasConfigurationProperties传给构造函数
• CAS 5.x推荐使用Java配置而非XML，尽量避免修改deployerConfigContext.xml这类旧配置文件，以免和自动配置冲突

内容的提问来源于stack exchange，提问作者cquezel