授权认证配置与使用指南

使用指南概述

本文档详细介绍BladeX AI授权认证体系的配置方法、使用技巧和最佳实践，帮助开发者快速掌握认证体系的使用方法。

一、快速开始

1.1 基础配置

最简配置

只需要在Controller或方法上添加@ApiAuth注解即可启用认证功能。

@RestController
@RequestMapping("/api/v1/models")
@ApiAuth  // 启用认证，默认需要超级密钥
public class ModelController {
    
    @GetMapping("/list")
    public List<ModelInfo> getModelList() {
        // 需要超级密钥(sk-)才能访问
        return modelService.getAllModels();
    }
}

1.2 客户端调用示例

不同客户端的调用方式

支持多种编程语言和HTTP客户端的调用方式，包括cURL、JavaScript、Java、Python等主流开发环境。

cURL命令

curl -X GET "https://api.example.com/api/v1/models/list" \
     -H "Authorization: Bearer sk-1234567890abcdef1234567890abcdef12345678"

JavaScript (Axios)

const response = await axios.get('/api/v1/models/list', {
    headers: {
        'Authorization': 'Bearer sk-1234567890abcdef1234567890abcdef12345678'
    }
});

Java (OkHttp)

Request request = new Request.Builder()
    .url("https://api.example.com/api/v1/models/list")
    .header("Authorization", "Bearer sk-1234567890abcdef1234567890abcdef12345678")
    .build();

Python (Requests)

headers = {
    'Authorization': 'Bearer sk-1234567890abcdef1234567890abcdef12345678'
}
response = requests.get('https://api.example.com/api/v1/models/list', headers=headers)

二、认证模式详解

2.1 超级密钥模式 (SUPER_KEY)

最高权限模式

超级密钥拥有访问所有API接口的权限，适用于系统管理、集成开发等场景。

@RestController
@ApiAuth(mode = ApiAuthMode.SUPER_KEY)
public class AdminController {
    
    @PostMapping("/system/config")
    public Result updateSystemConfig(@RequestBody ConfigRequest request) {
        // 只有超级密钥可以访问
        return adminService.updateConfig(request);
    }
    
    @GetMapping("/users")
    public List<User> getAllUsers() {
        // 只有超级密钥可以访问
        return userService.getAllUsers();
    }
}

适用场景：

• 系统配置管理
• 用户权限管理
• 平台监控和运维
• 第三方系统集成

2.2 工作流密钥模式 (FLOW_KEY)

业务权限模式

工作流密钥适用于智能体应用和自动化流程，具有工作流相关的操作权限。

@RestController
@RequestMapping("/api/v1/flow")
@ApiAuth(mode = ApiAuthMode.FLOW_KEY)
public class FlowController {
    
    @PostMapping("/execute")
    public FlowResult executeFlow(@RequestBody FlowRequest request) {
        // 工作流密钥(fk-)或超级密钥(sk-)可以访问
        return flowService.execute(request);
    }
    
    @GetMapping("/{flowId}/status")
    public FlowStatus getFlowStatus(@PathVariable Long flowId) {
        // 工作流密钥(fk-)或超级密钥(sk-)可以访问
        return flowService.getStatus(flowId);
    }
}

适用场景：

• 智能体对话执行
• 工作流状态查询
• 自动化任务处理
• 业务流程编排

2.3 知识库密钥模式 (KNOWLEDGE_KEY)

专项权限模式

知识库密钥专门用于文档检索和知识库相关操作，提供精确的权限控制。

@RestController
@RequestMapping("/api/v1/knowledge")
@ApiAuth(mode = ApiAuthMode.KNOWLEDGE_KEY)
public class KnowledgeController {
    
    @PostMapping("/search")
    public SearchResult search(@RequestBody SearchRequest request) {
        // 知识库密钥(kk-)或超级密钥(sk-)可以访问
        return knowledgeService.search(request);
    }
    
    @GetMapping("/{kbId}/documents")
    public List<Document> getDocuments(@PathVariable Long kbId) {
        // 知识库密钥(kk-)或超级密钥(sk-)可以访问
        return knowledgeService.getDocuments(kbId);
    }
}

适用场景：

• 文档检索查询
• RAG知识问答
• 知识库内容管理
• 语义搜索服务

三、高级配置技巧

3.1 混合权限配置

灵活权限控制

通过类级别和方法级别注解的组合，实现灵活的权限控制策略。

@RestController
@RequestMapping("/api/v1/ai")
@ApiAuth(mode = ApiAuthMode.SUPER_KEY)  // 类级别：默认需要超级密钥
public class AIController {
    
    // 继承类级别配置
    @GetMapping("/models")
    public List<Model> getModels() {
        // 需要超级密钥
    }
    
    // 方法级别覆盖：降低权限要求
    @ApiAuth(mode = ApiAuthMode.FLOW_KEY)
    @PostMapping("/chat")
    public ChatResponse chat(@RequestBody ChatRequest request) {
        // 工作流密钥或超级密钥均可访问
    }
    
    // 方法级别覆盖：禁用认证
    @ApiAuth(false)
    @GetMapping("/health")
    public HealthStatus health() {
        // 公开接口，无需认证
    }
    
    // 方法级别覆盖：提高权限要求
    @ApiAuth(mode = ApiAuthMode.SUPER_KEY, message = "需要管理员权限")
    @DeleteMapping("/models/{id}")
    public Result deleteModel(@PathVariable Long id) {
        // 强制需要超级密钥，自定义错误消息
    }
}

3.2 条件认证配置

动态权限控制

根据不同的业务条件动态调整认证要求。

@RestController
public class ConditionalAuthController {
    
    @ApiAuth(mode = ApiAuthMode.FLOW_KEY)
    @PostMapping("/process")
    public Result processData(@RequestBody ProcessRequest request) {
        // 在方法内部可以获取当前用户的权限信息
        TokenValidationResult authResult = getCurrentAuthResult();
        
        if (authResult.getKeyType() == ApiKeyType.SUPER) {
            // 超级密钥可以处理所有类型的数据
            return processAllData(request);
        } else {
            // 工作流密钥只能处理特定类型的数据
            return processLimitedData(request);
        }
    }
}

3.3 批量认证配置

统一配置管理

通过配置类或基础Controller实现批量认证配置。

// 基础Controller，统一认证配置
@ApiAuth(mode = ApiAuthMode.SUPER_KEY)
public abstract class BaseAdminController {
    // 所有继承的Controller都需要超级密钥
}

// 业务Controller继承基础配置
@RestController
@RequestMapping("/admin/users")
public class UserAdminController extends BaseAdminController {
    
    @GetMapping
    public List<User> getUsers() {
        // 自动继承超级密钥要求
    }
    
    @ApiAuth(mode = ApiAuthMode.FLOW_KEY)  // 可以覆盖基础配置
    @GetMapping("/public")
    public List<User> getPublicUsers() {
        // 降低权限要求
    }
}

四、错误处理和调试

4.1 常见错误类型

认证错误分类

了解不同类型的认证错误，有助于快速定位和解决问题。

HTTP状态码	错误类型	可能原因	解决方案
401	Unauthorized	Token缺失或格式错误	检查Authorization头格式
403	Forbidden	权限不足	确认密钥类型与接口要求匹配
400	Bad Request	请求格式错误	检查请求参数和Token格式

4.2 错误响应示例

标准错误响应格式

系统返回统一的JSON格式错误响应，包含错误代码、消息、时间戳等关键信息。

{
    "code": 401,
    "message": "需要超级密钥(sk-)才能访问",
    "timestamp": 1703123456789,
    "path": "/api/v1/models",
    "error": "Unauthorized"
}

4.3 调试技巧

调试方法

提供多种调试方法帮助开发者快速定位和解决认证问题。

1. 日志级别调整

logging:
  level:
    org.springblade.modules.aigc.api.auth: DEBUG

2. 认证信息打印

@GetMapping("/debug/auth")
@ApiAuth(mode = ApiAuthMode.FLOW_KEY)
public Map<String, Object> debugAuth() {
    TokenValidationResult result = getCurrentAuthResult();
    Map<String, Object> info = new HashMap<>();
    info.put("keyType", result.getKeyType());
    info.put("userId", result.getUserId());
    info.put("moduleId", result.getModuleId());
    return info;
}

3. Token验证测试

@RestController
public class AuthTestController {
    
    @Autowired
    private TokenAuthenticator tokenAuthenticator;
    
    @PostMapping("/test/token")
    @ApiAuth(false)  // 禁用认证，用于测试
    public TokenValidationResult testToken(@RequestBody String token) {
        return tokenAuthenticator.validateTokenDetail(token);
    }
}

五、安全最佳实践

5.1 密钥管理

密钥安全策略

• 定期轮换：建议每30-90天轮换一次API密钥
• 权限最小化：为应用分配最小必要权限的密钥类型
• 安全存储：使用环境变量或密钥管理服务存储密钥
• 访问监控：定期审计密钥使用情况和访问日志

// 配置示例：从环境变量读取密钥
@Configuration
public class ApiKeyConfig {
    
    @Value("${app.api.super-key}")
    private String superKey;
    
    @Value("${app.api.flow-key}")
    private String flowKey;
    
    // 不要在代码中硬编码密钥
}

5.2 网络安全

传输安全

• HTTPS强制：生产环境必须使用HTTPS传输
• 请求签名：关键接口可增加请求签名验证
• 频率限制：实施API调用频率限制，防止滥用
• IP白名单：对敏感接口配置IP访问白名单

// 频率限制示例
@RestController
public class RateLimitedController {
    
    @RateLimiter(name = "api", fallbackMethod = "rateLimitFallback")
    @ApiAuth(mode = ApiAuthMode.SUPER_KEY)
    @GetMapping("/sensitive-data")
    public Result getSensitiveData() {
        return dataService.getSensitiveData();
    }
    
    public Result rateLimitFallback(Exception ex) {
        return Result.fail("访问频率过高，请稍后重试");
    }
}

5.3 监控和告警

安全监控

建议配置以下监控指标和告警规则：

• 认证失败次数异常增长
• 单个密钥的异常访问模式
• 敏感接口的访问频率监控
• 新IP地址的首次访问告警

// 监控埋点示例
@Component
public class AuthMetrics {
    
    private final MeterRegistry meterRegistry;
    
    public void recordAuthSuccess(String keyType) {
        Counter.builder("auth.success")
            .tag("key_type", keyType)
            .register(meterRegistry)
            .increment();
    }
    
    public void recordAuthFailure(String reason) {
        Counter.builder("auth.failure")
            .tag("reason", reason)
            .register(meterRegistry)
            .increment();
    }
}

六、集成示例

6.1 Spring Boot集成

完整集成示例

展示在Spring Boot应用中完整集成BladeX AI认证体系的配置方法。

@SpringBootApplication
@EnableAspectJAutoProxy  // 启用AOP
public class AIApplication {
    
    public static void main(String[] args) {
        SpringApplication.run(AIApplication.class, args);
    }
    
    // 自定义认证配置
    @Bean
    @ConditionalOnMissingBean
    public TokenValidator tokenValidator() {
        return new BladeTokenValidator();
    }
    
    // 认证异常处理器
    @Bean
    public ApiAuthExceptionHandler authExceptionHandler() {
        return new ApiAuthExceptionHandler();
    }
}

6.2 Gateway集成

网关层认证

在API网关层也可以进行初步的认证过滤。

@Component
public class AuthGatewayFilter implements GlobalFilter {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getPath().value();
        
        // 对特定路径进行预认证
        if (path.startsWith("/api/v1/admin/")) {
            String token = extractToken(exchange.getRequest());
            if (!isSuperKey(token)) {
                return unauthorized(exchange);
            }
        }
        
        return chain.filter(exchange);
    }
}

通过以上配置和使用指南，开发者可以快速掌握BladeX AI授权认证体系的使用方法，构建安全可靠的AI应用系统。