auth-module-architecture

1
0
Source

Auth 权限认证模块架构指南,涵盖 IAM 集成、RBAC 权限模型、资源权限校验、权限迁移、OAuth 认证。当用户开发权限功能、配置 IAM 资源、实现权限校验或处理认证流程时使用。

Install

mkdir -p .claude/skills/auth-module-architecture && curl -L -o skill.zip "https://mcp.directory/api/skills/download/4185" && unzip -o skill.zip -d .claude/skills/auth-module-architecture && rm skill.zip

Installs to .claude/skills/auth-module-architecture

About this skill

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-authREST API 接口定义50+
biz-auth业务逻辑、RBAC 实现150+
model-authJOOQ 数据模型自动生成

二、核心概念

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_CALLBACKIAM 回调ID, GATEWAY, PATH, RESOURCE, SYSTEM

4.4 OAuth2 相关表

表名说明
T_AUTH_OAUTH2_CLIENT_DETAILSOAuth2 客户端信息
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/oauth2OAuth2 服务端点

5.2 RBAC Provider 层(核心服务)

类名文件大小职责
RbacPermissionService32KB权限校验核心,对接 IAM SDK
RbacPermissionResourceGroupService33KB用户组 CRUD 管理
RbacPermissionResourceMemberService29KB组成员管理
RbacPermissionResourceService21KB资源注册与管理
RbacPermissionManageFacadeServiceImpl117KB权限管理门面(最大)
RbacPermissionResourceGroupPermissionService39KB组权限管理
RbacPermissionResourceGroupSyncService37KB组同步服务
PermissionGradeManagerService27KB分级管理员
RbacPermissionApplyService30KB权限申请服务

5.3 通用 Service 层

类名职责
PermissionAuthorizationServiceImpl资源授权(代持人)管理
AuthDeptServiceImpl部门信息服务
ManagerUserService超级管理员管理
StrategyService权限策略管理
ThirdLoginService第三方登录
AuthUserBlackListService用户黑名单

5.4 DAO 层

类名文件大小职责
AuthResourceGroupMemberDao34KB组成员数据访问(最大)
AuthResourceGroupDao19KB用户组数据访问
AuthResourceDao15KB资源数据访问
AuthResourceGroupPermissionDao11KB组权限数据访问
AuthAuthorizationDao10KB授权数据访问

六、核心流程

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(权限中心),核心依赖:

// IAM SDK 核心类
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 回调接口

// 资源回调接口 - 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 配置类

// 位置:biz-auth/provider/rbac/config/RbacAuthConfiguration.kt (37KB)
@Configuration
class RbacAuthConfiguration {
    // IAM 客户端配置
    // 权限服务 Bean 定义
    // 缓存配置
}

8.2 MQ 配置

// 位置:biz-auth/provider/rbac/config/RbacMQConfiguration.kt
// 定义权限相关的消息队列
// - 组创建事件
// - 组修改事件
// - ITSM 回调事件
// - 权限同步事件

九、开发规范

9.1 新增权限操作

  1. T_AUTH_ACTION 表添加操作定义
  2. AuthPermission 枚举中添加对应值
  3. 在 IAM 系统注册操作
  4. 更新 RbacAuthUtils.buildAction() 映射

9.2 新增资源类型

  1. AuthResourceType 枚举中添加类型
  2. T_AUTH_RESOURCE_TYPE 表添加记录
  3. 实现 AuthResourceCallBackResource 回调接口
  4. 在 IAM 系统注册资源类型

9.3 权限校验示例

// 服务间调用校验权限
client.get(ServicePermissionAuthResource::class).validateUserResourcePermission(
    userId = userId,
    token = token,
    action = AuthPermission.EXECUTE.value,
    projectCode = projectCode,
    resourceCode = AuthResourceType.PIPELINE_DEFAULT.value
)

// 使用 AuthPermissionApi
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

More by TencentBlueKing

View all →

store-module-architecture

TencentBlueKing

Store 研发商店模块架构指南,涵盖插件/模板/镜像管理、版本发布、审核流程、商店市场、扩展点机制。当用户开发研发商店功能、发布插件、管理模板或实现扩展点时使用。

00

00-bkci-global-architecture

TencentBlueKing

BK-CI 全局架构指南,以流水线为核心的模块协作全景图,涵盖完整执行流程、模块依赖关系、数据流向、核心概念。当用户需要理解系统架构、进行跨模块开发、了解模块间协作或规划架构设计时优先阅读。

10

go-agent-development

TencentBlueKing

Go Agent 开发指南,涵盖 Agent 架构设计、心跳机制、任务执行、日志上报、升级流程、与 Dispatch 模块交互。当用户开发构建机 Agent、实现任务执行逻辑、处理 Agent 通信或进行 Go 语言开发时使用。

00

supporting-modules-architecture

TencentBlueKing

BK-CI 支撑模块架构指南,涵盖凭证管理(Ticket)、构建机环境(Environment)、通知服务(Notify)、构建日志(Log)、质量红线(Quality)、开放接口(OpenAPI)等支撑性服务模块。当用户开发这些模块功能或需要理解支撑服务架构时使用。

100

yaml-pipeline-transfer

TencentBlueKing

YAML 流水线转换指南,涵盖 YAML 与 Model 双向转换、PAC(Pipeline as Code)实现、模板引用、触发器配置。当用户需要解析 YAML 流水线、实现 PAC 模式、处理流水线模板或进行 YAML 语法校验时使用。

20

design-patterns

TencentBlueKing

BK-CI 项目设计模式实践指南,涵盖工厂模式、策略模式、观察者模式、装饰器模式、模板方法等在项目中的实际应用。当用户学习设计模式、重构代码、设计可扩展架构或理解项目设计时使用。

80

You might also like

flutter-development

aj-geddes

Build beautiful cross-platform mobile apps with Flutter and Dart. Covers widgets, state management with Provider/BLoC, navigation, API integration, and material design.

298793

drawio-diagrams-enhanced

jgtolentino

Create professional draw.io (diagrams.net) diagrams in XML format (.drawio files) with integrated PMP/PMBOK methodologies, extensive visual asset libraries, and industry-standard professional templates. Use this skill when users ask to create flowcharts, swimlane diagrams, cross-functional flowcharts, org charts, network diagrams, UML diagrams, BPMN, project management diagrams (WBS, Gantt, PERT, RACI), risk matrices, stakeholder maps, or any other visual diagram in draw.io format. This skill includes access to custom shape libraries for icons, clipart, and professional symbols.

220415

godot

bfollington

This skill should be used when working on Godot Engine projects. It provides specialized knowledge of Godot's file formats (.gd, .tscn, .tres), architecture patterns (component-based, signal-driven, resource-based), common pitfalls, validation tools, code templates, and CLI workflows. The `godot` command is available for running the game, validating scripts, importing resources, and exporting builds. Use this skill for tasks involving Godot game development, debugging scene/resource files, implementing game systems, or creating new Godot components.

216298

nano-banana-pro

garg-aayush

Generate and edit images using Google's Nano Banana Pro (Gemini 3 Pro Image) API. Use when the user asks to generate, create, edit, modify, change, alter, or update images. Also use when user references an existing image file and asks to modify it in any way (e.g., "modify this image", "change the background", "replace X with Y"). Supports both text-to-image generation and image-to-image editing with configurable resolution (1K default, 2K, or 4K for high resolution). DO NOT read the image file first - use this skill directly with the --input-image parameter.

224234

ui-ux-pro-max

nextlevelbuilder

"UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient."

176201

rust-coding-skill

UtakataKyosui

Guides Claude in writing idiomatic, efficient, well-structured Rust code using proper data modeling, traits, impl organization, macros, and build-speed best practices.

167173

Stay ahead of the MCP ecosystem

Get weekly updates on new skills and servers.