授权认证二次开发定制指南

定制开发概述

BladeX AI授权认证体系提供了完善的扩展接口和自定义能力，支持企业根据自身业务需求进行深度定制。本文档详细介绍认证体系的扩展方法和二次开发指南。

一、自定义认证模式

1.1 扩展认证模式枚举

新增认证模式

通过扩展ApiAuthMode枚举，可以添加新的认证模式以满足特殊业务需求。

public enum ApiAuthMode {
    SUPER_KEY,         // 超级密钥
    FLOW_KEY,          // 工作流密钥
    KNOWLEDGE_KEY,     // 知识库密钥
    
    // 自定义认证模式
    TENANT_KEY,        // 租户密钥
    DEPARTMENT_KEY,    // 部门密钥
    PROJECT_KEY        // 项目密钥
}

1.2 密钥前缀配置

密钥格式扩展

为新的认证模式定义相应的密钥前缀和验证规则。

public interface ApiKeyConstant {
    String SUPER_KEY = "sk-";
    String FLOW_KEY = "fk-";
    String KNOWLEDGE_KEY = "kk-";
    
    // 新增密钥前缀
    String TENANT_KEY = "tk-";
    String DEPARTMENT_KEY = "dk-";
    String PROJECT_KEY = "pk-";
}

1.3 认证逻辑扩展

切面处理器扩展

修改ApiAuthAspect以支持新的认证模式验证逻辑。

@Aspect
@Component
public class ExtendedApiAuthAspect extends ApiAuthAspect {
    
    @Override
    protected boolean validatePermission(ApiAuth apiAuth, String token, 
                                       TokenValidationResult result) {
        ApiKeyType keyType = result.getKeyType();
        ApiAuthMode mode = apiAuth.mode();
        
        // 扩展验证逻辑
        switch (mode) {
            case TENANT_KEY:
                return validateTenantPermission(token, keyType);
            case DEPARTMENT_KEY:
                return validateDepartmentPermission(token, keyType);
            case PROJECT_KEY:
                return validateProjectPermission(token, keyType);
            default:
                return super.validatePermission(apiAuth, token, result);
        }
    }
    
    private boolean validateTenantPermission(String token, ApiKeyType keyType) {
        // 租户权限验证逻辑
        if (keyType == ApiKeyType.SUPER || keyType == ApiKeyType.TENANT) {
            return tenantValidator.validateAccess(token);
        }
        return false;
    }
}

二、自定义Token验证器

2.1 实现验证器接口

自定义验证逻辑

通过实现TokenValidator接口，可以添加完全自定义的Token验证逻辑。

@Component
@Primary  // 优先使用自定义实现
public class EnterpriseTokenValidator implements TokenValidator {
    
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    @Autowired
    private TenantService tenantService;
    
    @Override
    public boolean validate(String token) {
        // 1. 基础格式验证
        if (!isValidFormat(token)) {
            return false;
        }
        
        // 2. 缓存验证
        Boolean cached = getCachedResult(token);
        if (cached != null) {
            return cached;
        }
        
        // 3. 业务验证
        boolean valid = performBusinessValidation(token);
        
        // 4. 缓存结果
        cacheResult(token, valid);
        
        return valid;
    }
    
    @Override
    public TokenValidationResult validateToken(String token) {
        // 详细验证实现
        return TokenValidationResult.builder()
            .valid(validate(token))
            .userId(extractUserId(token))
            .tenantId(extractTenantId(token))
            .permissions(extractPermissions(token))
            .build();
    }
    
    private boolean performBusinessValidation(String token) {
        // 自定义业务验证逻辑
        String keyType = getKeyPrefix(token);
        
        switch (keyType) {
            case "tk-":  // 租户密钥
                return validateTenantKey(token);
            case "dk-":  // 部门密钥
                return validateDepartmentKey(token);
            default:
                return defaultValidation(token);
        }
    }
}

2.2 多级缓存策略

性能优化

实现多级缓存策略，提升验证性能。

@Component
public class CachedTokenValidator implements TokenValidator {
    
    // L1缓存：内存缓存
    private final Cache<String, TokenValidationResult> memoryCache;
    
    // L2缓存：Redis缓存
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    public CachedTokenValidator() {
        this.memoryCache = Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(5))
            .build();
    }
    
    @Override
    public TokenValidationResult validateToken(String token) {
        // 1. 检查内存缓存
        TokenValidationResult result = memoryCache.getIfPresent(token);
        if (result != null) {
            return result;
        }
        
        // 2. 检查Redis缓存
        result = getFromRedisCache(token);
        if (result != null) {
            memoryCache.put(token, result);
            return result;
        }
        
        // 3. 执行实际验证
        result = performValidation(token);
        
        // 4. 更新缓存
        memoryCache.put(token, result);
        putToRedisCache(token, result);
        
        return result;
    }
}

三、权限控制扩展

3.1 基于角色的权限控制

RBAC集成

集成基于角色的访问控制（RBAC），实现更精细的权限管理。

@Component
public class RBACAuthenticator {
    
    @Autowired
    private RoleService roleService;
    
    @Autowired
    private PermissionService permissionService;
    
    public boolean hasPermission(String token, String resource, String action) {
        // 1. 获取用户角色
        List<Role> roles = getUserRoles(token);
        
        // 2. 检查角色权限
        for (Role role : roles) {
            if (roleHasPermission(role, resource, action)) {
                return true;
            }
        }
        
        return false;
    }
    
    private boolean roleHasPermission(Role role, String resource, String action) {
        List<Permission> permissions = permissionService.getByRole(role.getId());
        return permissions.stream()
            .anyMatch(p -> p.getResource().equals(resource) && 
                          p.getAction().equals(action));
    }
}

// 使用示例
@RestController
public class ResourceController {
    
    @Autowired
    private RBACAuthenticator rbacAuth;
    
    @ApiAuth(mode = ApiAuthMode.SUPER_KEY)
    @GetMapping("/resources/{id}")
    public Resource getResource(@PathVariable Long id) {
        String token = getCurrentToken();
        
        // 检查细粒度权限
        if (!rbacAuth.hasPermission(token, "resource", "read")) {
            throw new ApiAuthException(403, "缺少资源读取权限");
        }
        
        return resourceService.getById(id);
    }
}

3.2 数据权限控制

行级权限

实现数据级别的权限控制，确保用户只能访问授权的数据。

@Component
public class DataPermissionFilter {
    
    public <T> List<T> filterByPermission(List<T> data, String token, 
                                         Class<T> entityClass) {
        // 获取用户数据权限范围
        DataPermission permission = getDataPermission(token, entityClass);
        
        return data.stream()
            .filter(item -> hasDataAccess(item, permission))
            .collect(Collectors.toList());
    }
    
    private DataPermission getDataPermission(String token, Class<?> entityClass) {
        // 根据token和实体类型获取数据权限
        TokenValidationResult auth = getCurrentAuthResult();
        return dataPermissionService.getPermission(
            auth.getUserId(), entityClass.getSimpleName()
        );
    }
}

四、多租户支持

4.1 租户隔离认证

租户认证体系

为多租户环境设计专门的认证和隔离机制。

@Component
public class TenantAwareTokenValidator implements TokenValidator {
    
    @Override
    public TokenValidationResult validateToken(String token) {
        // 1. 基础验证
        TokenValidationResult baseResult = baseValidator.validateToken(token);
        if (!baseResult.isValid()) {
            return baseResult;
        }
        
        // 2. 租户验证
        Long tenantId = extractTenantId(token);
        if (!isTenantActive(tenantId)) {
            return TokenValidationResult.invalid("租户已停用");
        }
        
        // 3. 租户权限验证
        if (!hastenantPermission(token, tenantId)) {
            return TokenValidationResult.invalid("无租户访问权限");
        }
        
        // 4. 设置租户上下文
        TenantContext.setCurrentTenant(tenantId);
        
        return baseResult;
    }
}

// 租户上下文管理
public class TenantContext {
    private static final ThreadLocal<Long> CURRENT_TENANT = new ThreadLocal<>();
    
    public static void setCurrentTenant(Long tenantId) {
        CURRENT_TENANT.set(tenantId);
    }
    
    public static Long getCurrentTenant() {
        return CURRENT_TENANT.get();
    }
    
    public static void clear() {
        CURRENT_TENANT.remove();
    }
}

4.2 租户数据隔离

自动数据隔离

在数据访问层自动添加租户过滤条件。

@Component
public class TenantDataInterceptor implements Interceptor {
    
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
        Object parameter = invocation.getArgs()[1];
        
        // 自动添加租户过滤条件
        if (needTenantFilter(ms)) {
            addTenantCondition(parameter);
        }
        
        return invocation.proceed();
    }
    
    private void addTenantCondition(Object parameter) {
        Long tenantId = TenantContext.getCurrentTenant();
        if (tenantId != null && parameter instanceof Map) {
            ((Map<String, Object>) parameter).put("tenantId", tenantId);
        }
    }
}

五、第三方认证集成

5.1 OAuth2集成

OAuth2认证

集成OAuth2认证，支持第三方身份提供商。

@Component
public class OAuth2TokenValidator implements TokenValidator {
    
    @Autowired
    private OAuth2TokenIntrospector tokenIntrospector;
    
    @Override
    public TokenValidationResult validateToken(String token) {
        // 1. 检查是否为OAuth2 token
        if (!isOAuth2Token(token)) {
            return delegateToDefault(token);
        }
        
        // 2. 调用OAuth2验证
        OAuth2TokenIntrospection introspection = 
            tokenIntrospector.introspect(token);
            
        if (!introspection.isActive()) {
            return TokenValidationResult.invalid("OAuth2 token已过期");
        }
        
        // 3. 转换为内部认证结果
        return convertToValidationResult(introspection);
    }
    
    private TokenValidationResult convertToValidationResult(
            OAuth2TokenIntrospection introspection) {
        return TokenValidationResult.builder()
            .valid(true)
            .userId(extractUserId(introspection))
            .username(introspection.getUsername())
            .keyType(ApiKeyType.OAUTH2)
            .permissions(extractPermissions(introspection))
            .build();
    }
}

5.2 JWT Token支持

JWT认证

支持JWT Token的验证和解析。

@Component
public class JWTTokenValidator implements TokenValidator {
    
    @Value("${app.jwt.secret}")
    private String jwtSecret;
    
    @Override
    public TokenValidationResult validateToken(String token) {
        try {
            // 1. 验证JWT签名
            Claims claims = Jwts.parser()
                .setSigningKey(jwtSecret)
                .parseClaimsJws(token)
                .getBody();
            
            // 2. 检查过期时间
            if (claims.getExpiration().before(new Date())) {
                return TokenValidationResult.invalid("JWT token已过期");
            }
            
            // 3. 提取用户信息
            return TokenValidationResult.builder()
                .valid(true)
                .userId(claims.get("userId", Long.class))
                .username(claims.getSubject())
                .keyType(ApiKeyType.JWT)
                .build();
                
        } catch (JwtException e) {
            return TokenValidationResult.invalid("JWT token无效: " + e.getMessage());
        }
    }
}

六、监控和审计扩展

6.1 认证事件监听

事件驱动监控

通过事件机制实现认证行为的监控和审计。

// 认证事件定义
public class AuthEvent {
    private String token;
    private String endpoint;
    private boolean success;
    private String errorMessage;
    private Long timestamp;
    // getter/setter...
}

// 事件发布器
@Component
public class AuthEventPublisher {
    
    @Autowired
    private ApplicationEventPublisher eventPublisher;
    
    public void publishAuthSuccess(String token, String endpoint) {
        AuthEvent event = new AuthEvent();
        event.setToken(maskToken(token));
        event.setEndpoint(endpoint);
        event.setSuccess(true);
        event.setTimestamp(System.currentTimeMillis());
        
        eventPublisher.publishEvent(event);
    }
    
    public void publishAuthFailure(String token, String endpoint, String error) {
        AuthEvent event = new AuthEvent();
        event.setToken(maskToken(token));
        event.setEndpoint(endpoint);
        event.setSuccess(false);
        event.setErrorMessage(error);
        event.setTimestamp(System.currentTimeMillis());
        
        eventPublisher.publishEvent(event);
    }
}

// 事件监听器
@Component
public class AuthEventListener {
    
    @EventListener
    public void handleAuthEvent(AuthEvent event) {
        // 记录审计日志
        auditService.recordAuthEvent(event);
        
        // 安全监控
        if (!event.isSuccess()) {
            securityMonitor.detectSuspiciousActivity(event);
        }
        
        // 统计指标
        metricsService.recordAuthMetric(event);
    }
}

6.2 实时安全监控

异常检测

实现实时的安全威胁检测和响应机制。

@Component
public class SecurityMonitor {
    
    private final Map<String, AtomicInteger> failureCount = new ConcurrentHashMap<>();
    private final Map<String, Long> lastFailureTime = new ConcurrentHashMap<>();
    
    public void detectSuspiciousActivity(AuthEvent event) {
        String clientIp = event.getClientIp();
        
        // 1. 频繁失败检测
        if (isFrequentFailure(clientIp)) {
            triggerSecurityAlert("频繁认证失败", clientIp);
            blockIpTemporarily(clientIp);
        }
        
        // 2. 异常访问模式检测
        if (isAbnormalAccessPattern(event)) {
            triggerSecurityAlert("异常访问模式", clientIp);
        }
        
        // 3. 暴力破解检测
        if (isBruteForceAttack(clientIp)) {
            triggerSecurityAlert("疑似暴力破解", clientIp);
            blockIpPermanently(clientIp);
        }
    }
    
    private boolean isFrequentFailure(String clientIp) {
        AtomicInteger count = failureCount.computeIfAbsent(clientIp, 
            k -> new AtomicInteger(0));
        int failures = count.incrementAndGet();
        
        // 5分钟内失败超过10次
        return failures > 10 && 
               (System.currentTimeMillis() - lastFailureTime.getOrDefault(clientIp, 0L)) 
               < TimeUnit.MINUTES.toMillis(5);
    }
}

七、配置化扩展

7.1 动态配置支持

运行时配置

支持运行时动态调整认证配置，无需重启服务。

@Component
@ConfigurationProperties(prefix = "app.auth")
public class DynamicAuthConfig {
    
    private boolean enabled = true;
    private int maxRetries = 3;
    private Duration lockoutDuration = Duration.ofMinutes(15);
    private List<String> trustedIps = new ArrayList<>();
    
    // 动态配置更新
    @EventListener
    public void handleConfigChange(ConfigChangeEvent event) {
        if (event.getKey().startsWith("app.auth")) {
            refreshConfig();
        }
    }
    
    private void refreshConfig() {
        // 从配置中心重新加载配置
        ConfigService.refreshConfig(this);
        
        // 通知相关组件配置已更新
        applicationEventPublisher.publishEvent(
            new AuthConfigUpdatedEvent(this)
        );
    }
}

7.2 策略配置化

策略引擎

通过配置化的方式定义认证策略和规则。

@Component
public class ConfigurableAuthStrategy {
    
    @Autowired
    private AuthPolicyRepository policyRepository;
    
    public boolean evaluate(String token, String endpoint, String method) {
        // 1. 获取适用的策略
        List<AuthPolicy> policies = policyRepository
            .findApplicablePolicies(endpoint, method);
        
        // 2. 逐一评估策略
        for (AuthPolicy policy : policies) {
            if (!evaluatePolicy(policy, token, endpoint, method)) {
                return false;
            }
        }
        
        return true;
    }
    
    private boolean evaluatePolicy(AuthPolicy policy, String token, 
                                 String endpoint, String method) {
        // 根据策略类型执行不同的评估逻辑
        switch (policy.getType()) {
            case TIME_BASED:
                return evaluateTimePolicy(policy, token);
            case IP_BASED:
                return evaluateIpPolicy(policy, token);
            case ROLE_BASED:
                return evaluateRolePolicy(policy, token);
            default:
                return true;
        }
    }
}

通过以上扩展方案，BladeX AI授权认证体系可以灵活适应各种复杂的企业级需求，为不同场景提供定制化的安全解决方案。