| name | auth-module-architecture |
| description | Auth 权限认证模块架构指南，涵盖 IAM 集成、RBAC 权限模型、资源权限校验、权限迁移、OAuth 认证。当用户开发权限功能、配置 IAM 资源、实现权限校验或处理认证流程时使用。 |
Auth 权限认证模块架构指南
模块定位: Auth 是 BK-CI 的权限认证核心模块，负责用户认证、权限校验、用户组管理、OAuth2 认证等功能，采用 RBAC（基于角色的访问控制）模型。
一、模块整体结构
1.1 子模块划分
src/backend/ci/core/auth/
├── api-auth/ # API 接口定义层
│ └── src/main/kotlin/com/tencent/devops/auth/
│ ├── api/
│ │ ├── callback/ # 回调接口（IAM、ITSM）
│ │ ├── login/ # 登录接口
│ │ ├── manager/ # 管理员接口
│ │ ├── migrate/ # 迁移接口
│ │ ├── oauth2/ # OAuth2 接口
│ │ ├── op/ # 运维接口
│ │ ├── open/ # 开放接口
│ │ ├── service/ # 服务间调用接口
│ │ ├── sync/ # 同步接口
│ │ └── user/ # 用户接口
│ ├── constant/ # 常量定义
│ └── pojo/ # 数据对象
│
├── biz-auth/ # 业务逻辑层
│ └── src/main/kotlin/com/tencent/devops/auth/
│ ├── aspect/ # AOP 切面
│ ├── common/ # 通用配置
│ ├── cron/ # 定时任务
│ ├── dao/ # 数据访问层（40+ 文件）
│ ├── entity/ # 实体定义
│ ├── filter/ # 过滤器
│ ├── provider/
│ │ ├── rbac/ # RBAC 实现（核心）
│ │ └── sample/ # 示例实现
│ ├── refresh/ # 刷新机制
│ ├── resources/ # API 实现
│ ├── service/ # 业务服务（30+ 文件）
│ ├── sharding/ # 分片策略
│ └── utils/ # 工具类
│
├── boot-auth/ # Spring Boot 启动模块
└── model-auth/ # 数据模型层（JOOQ 生成）
1.2 模块职责矩阵
| 模块 | 职责 | 核心类数量 |
|---|
| api-auth | REST API 接口定义 | 50+ |
| biz-auth | 业务逻辑、RBAC 实现 | 150+ |
| model-auth | JOOQ 数据模型 | 自动生成 |
二、核心概念
2.1 RBAC 权限模型
┌─────────────────────────────────────────────────────────────────────────┐
│ BK-CI RBAC 权限模型 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 用户 │────►│ 用户组 │────►│ 权限策略 │ │
│ │ (User) │ │ (Group) │ │ (Policy) │ │
│ └──────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ ┌──────────────────┐ │
│ │ │ │ 操作 │ │
│ │ │ │ (Action) │ │
│ │ │ │ create/view/edit │ │
│ │ │ │ delete/execute │ │
│ │ │ └────────┬─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 资源 (Resource) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ project │ │pipeline │ │ repo │ │ env │ ... │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 核心实体关系
| 实体 | 说明 | 对应表 |
|---|
| 用户 (User) | 系统用户 | T_AUTH_USER_INFO |
| 用户组 (Group) | 权限组，关联权限策略 | T_AUTH_RESOURCE_GROUP |
| 组成员 (Member) | 用户组成员关系 | T_AUTH_RESOURCE_GROUP_MEMBER |
| 资源 (Resource) | 被管理的资源 | T_AUTH_RESOURCE |
| 操作 (Action) | 资源上的操作 | T_AUTH_ACTION |
| 权限 (Permission) | 组对资源的权限 | T_AUTH_RESOURCE_GROUP_PERMISSION |
2.3 默认用户组类型
enum class DefaultGroupType {
MANAGER,
DEVELOPER,
MAINTAINER,
TESTER,
PM,
QC,
VIEWER
}
三、分层架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ 请求入口 │
│ HTTP Request / 服务间调用 / IAM 回调 / OAuth2 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API 层 (api-auth) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │UserAuth │ │ServicePerm │ │OpenProject │ │Oauth2Service │ │
│ │ApplyResource │ │AuthResource │ │AuthResource │ │EndpointRes │ │
│ │(用户权限申请) │ │(服务间鉴权) │ │(开放项目权限) │ │(OAuth2认证) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 (biz-auth) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ ResourceImpl 实现层 │ │
│ │ ServicePermissionAuthResourceImpl | OpenProjectAuthResourceImpl │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ RBAC Provider 层 (核心) │ │
│ │ RbacPermissionService - 权限校验核心服务 │ │
│ │ RbacPermissionResourceGroupService - 用户组管理服务 │ │
│ │ RbacPermissionResourceMemberService - 组成员管理服务 │ │
│ │ RbacPermissionResourceService - 资源管理服务 │ │
│ │ PermissionGradeManagerService - 分级管理员服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 通用 Service 层 │ │
│ │ PermissionAuthorizationService - 授权服务 │ │
│ │ AuthDeptServiceImpl - 部门服务 │ │
│ │ ManagerUserService - 管理员用户服务 │ │
│ │ StrategyService - 策略服务 │ │
│ │ AuthMonitorSpaceService - 监控空间服务 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ DAO 层 (biz-auth/dao) │
│ AuthResourceGroupDao | AuthResourceGroupMemberDao | AuthResourceDao │
│ AuthAuthorizationDao | AuthOauth2ClientDetailsDao | ... │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 数据层 (model-auth + MySQL) │
│ 数据库：devops_ci_auth（共 30+ 张表） │
└─────────────────────────────────────────────────────────────────────────┘
四、核心数据库表
4.1 用户组相关表
| 表名 | 说明 | 核心字段 |
|---|
T_AUTH_RESOURCE_GROUP | 资源用户组 | ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, GROUP_CODE, GROUP_NAME, IAM_GROUP_ID |
T_AUTH_RESOURCE_GROUP_MEMBER | 组成员关系 | ID, PROJECT_CODE, IAM_GROUP_ID, MEMBER_ID, MEMBER_TYPE, EXPIRED_TIME |
T_AUTH_RESOURCE_GROUP_PERMISSION | 组权限 | ID, PROJECT_CODE, RESOURCE_TYPE, IAM_GROUP_ID, ACTION, RESOURCE_CODE |
T_AUTH_RESOURCE_GROUP_CONFIG | 组配置 | ID, RESOURCE_TYPE, GROUP_CODE, GROUP_NAME, ACTIONS |
4.2 资源相关表
| 表名 | 说明 | 核心字段 |
|---|
T_AUTH_RESOURCE | 资源信息 | ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, RESOURCE_NAME, IAM_RESOURCE_CODE |
T_AUTH_RESOURCE_TYPE | 资源类型 | ID, RESOURCE_TYPE, NAME, PARENT, SYSTEM |
T_AUTH_ACTION | 操作定义 | ACTION, RESOURCE_TYPE, ACTION_NAME, ACTION_TYPE |
4.3 授权相关表
| 表名 | 说明 | 核心字段 |
|---|
T_AUTH_AUTHORIZATION | 资源授权 | ID, PROJECT_CODE, RESOURCE_TYPE, RESOURCE_CODE, HANDOVER_FROM, HANDOVER_TO |
T_AUTH_IAM_CALLBACK | IAM 回调 | ID, GATEWAY, PATH, RESOURCE, SYSTEM |
4.4 OAuth2 相关表
| 表名 | 说明 |
|---|
T_AUTH_OAUTH2_CLIENT_DETAILS | OAuth2 客户端信息 |
T_AUTH_OAUTH2_ACCESS_TOKEN | 访问令牌 |
T_AUTH_OAUTH2_REFRESH_TOKEN | 刷新令牌 |
T_AUTH_OAUTH2_CODE | 授权码 |
T_AUTH_OAUTH2_SCOPE | 授权范围 |
五、核心类速查
5.1 API 接口层
| 类名 | 路径前缀 | 职责 |
|---|
ServicePermissionAuthResource | /service/auth/permission | 服务间权限校验 |
ServiceProjectAuthResource | /service/auth/project | 服务间项目权限 |
ServiceResourceGroupResource | /service/auth/resource/group | 用户组管理 |
ServiceResourceMemberResource | /service/auth/resource/member | 组成员管理 |
UserAuthApplyResource | /user/auth/apply | 用户权限申请 |
UserAuthAuthorizationResource | /user/auth/authorization | 用户授权管理 |
OpenPermissionAuthResource | /open/auth/permission | 开放权限接口 |
OpenProjectAuthResource | /open/auth/project | 开放项目权限 |
Oauth2ServiceEndpointResource | /service/oauth2 | OAuth2 服务端点 |
5.2 RBAC Provider 层（核心服务）
| 类名 | 文件大小 | 职责 |
|---|
RbacPermissionService | 32KB | 权限校验核心，对接 IAM SDK |
RbacPermissionResourceGroupService | 33KB | 用户组 CRUD 管理 |
RbacPermissionResourceMemberService | 29KB | 组成员管理 |
RbacPermissionResourceService | 21KB | 资源注册与管理 |
RbacPermissionManageFacadeServiceImpl | 117KB | 权限管理门面（最大） |
RbacPermissionResourceGroupPermissionService | 39KB | 组权限管理 |
RbacPermissionResourceGroupSyncService | 37KB | 组同步服务 |
PermissionGradeManagerService | 27KB | 分级管理员 |
RbacPermissionApplyService | 30KB | 权限申请服务 |
5.3 通用 Service 层
| 类名 | 职责 |
|---|
PermissionAuthorizationServiceImpl | 资源授权（代持人）管理 |
AuthDeptServiceImpl | 部门信息服务 |
ManagerUserService | 超级管理员管理 |
StrategyService | 权限策略管理 |
ThirdLoginService | 第三方登录 |
AuthUserBlackListService | 用户黑名单 |
5.4 DAO 层
| 类名 | 文件大小 | 职责 |
|---|
AuthResourceGroupMemberDao | 34KB | 组成员数据访问（最大） |
AuthResourceGroupDao | 19KB | 用户组数据访问 |
AuthResourceDao | 15KB | 资源数据访问 |
AuthResourceGroupPermissionDao | 11KB | 组权限数据访问 |
AuthAuthorizationDao | 10KB | 授权数据访问 |
六、核心流程
6.1 权限校验流程
用户请求
│
▼
ServicePermissionAuthResource.validateUserResourcePermission()
│
▼
ServicePermissionAuthResourceImpl
│
▼
RbacPermissionService.validateUserResourcePermission()
│
├─► 检查是否超级管理员 (SuperManagerService)
├─► 检查项目成员缓存 (BkInternalPermissionCache)
│
▼
AuthHelper.isAllowed() ← IAM SDK
│
├─► 构建 ActionDTO (操作)
├─► 构建 ResourceDTO (资源)
└─► 调用 IAM 策略引擎
6.2 用户组创建流程
UserAuthApplyResource.createGroup()
│
▼
RbacPermissionResourceGroupService.createGroup()
│
├─► 校验组名长度 (5-32字符)
├─► 检查组名是否重复
│
▼
iamV2ManagerService.createRoleGroup() ← IAM SDK
│
▼
authResourceGroupDao.create() ← 保存到本地数据库
│
▼
permissionResourceGroupPermissionService.grantGroupPermission() ← 授予权限
6.3 OAuth2 认证流程
┌─────────────────────────────────────────────────────────────────┐
│ OAuth2 授权码模式 │
├─────────────────────────────────────────────────────────────────┤
│ 1. 客户端请求授权 │
│ GET /oauth2/authorize?client_id=xxx&redirect_uri=xxx │
│ │ │
│ ▼ │
│ 2. 用户登录并授权 │
│ Oauth2DesktopEndpointResource.authorize() │
│ │ │
│ ▼ │
│ 3. 返回授权码 │
│ redirect_uri?code=xxx │
│ │ │
│ ▼ │
│ 4. 客户端用授权码换取 Token │
│ POST /oauth2/token │
│ Oauth2ServiceEndpointResource.getToken() │
│ │ │
│ ▼ │
│ 5. 返回 Access Token + Refresh Token │
└─────────────────────────────────────────────────────────────────┘
七、与 IAM 集成
7.1 IAM SDK 依赖
Auth 模块深度集成腾讯蓝鲸 IAM（权限中心），核心依赖：
import com.tencent.bk.sdk.iam.config.IamConfiguration
import com.tencent.bk.sdk.iam.helper.AuthHelper
import com.tencent.bk.sdk.iam.service.PolicyService
import com.tencent.bk.sdk.iam.service.v2.V2ManagerService
7.2 IAM 回调接口
@Path("/open/auth/resource/callback")
interface OpenAuthResourceCallBackResource {
fun getResource(...)
fun listResource(...)
fun searchResource(...)
}
7.3 资源类型定义
enum class AuthResourceType(val value: String) {
PROJECT("project"),
PIPELINE_DEFAULT("pipeline"),
PIPELINE_GROUP("pipeline_group"),
PIPELINE_TEMPLATE("pipeline_template"),
CREDENTIAL("credential"),
CERT("cert"),
CGS("cgs"),
ENVIRONMENT_ENVIRONMENT("environment"),
ENVIRONMENT_ENV_NODE("env_node"),
CODE_REPERTORY("repertory"),
EXPERIENCE_TASK("experience_task"),
EXPERIENCE_GROUP("experience_group"),
QUALITY_RULE("rule"),
QUALITY_GROUP("quality_group"),
}
八、配置说明
8.1 RBAC 配置类
@Configuration
class RbacAuthConfiguration {
}
8.2 MQ 配置
九、开发规范
9.1 新增权限操作
- 在
T_AUTH_ACTION 表添加操作定义
- 在
AuthPermission 枚举中添加对应值
- 在 IAM 系统注册操作
- 更新
RbacAuthUtils.buildAction() 映射
9.2 新增资源类型
- 在
AuthResourceType 枚举中添加类型
- 在
T_AUTH_RESOURCE_TYPE 表添加记录
- 实现
AuthResourceCallBackResource 回调接口
- 在 IAM 系统注册资源类型
9.3 权限校验示例
client.get(ServicePermissionAuthResource::class).validateUserResourcePermission(
userId = userId,
token = token,
action = AuthPermission.EXECUTE.value,
projectCode = projectCode,
resourceCode = AuthResourceType.PIPELINE_DEFAULT.value
)
authPermissionApi.validateUserResourcePermission(
user = userId,
serviceCode = authServiceCode,
resourceType = AuthResourceType.PIPELINE_DEFAULT,
projectCode = projectCode,
resourceCode = pipelineId,
permission = AuthPermission.EXECUTE
)
十、常见问题
Q: 如何判断用户是否是项目成员？
A: 调用 RbacPermissionService.validateUserProjectPermission() 或检查用户是否在任意项目用户组中。
Q: 如何给用户授权？
A: 将用户添加到对应的用户组 RbacPermissionResourceMemberService.addGroupMember()。
Q: OAuth2 支持哪些授权模式？
A: 支持授权码模式（Authorization Code）和密码模式（Password）。
Q: 如何处理权限缓存？
A: 使用 BkInternalPermissionCache 进行缓存，通过 Redis 存储，支持主动刷新。
版本: 1.0.0 | 更新日期: 2025-12-10
