auth

README

auth — 认证与授权

基于 Casbin 实现的 RBAC/ABAC 鉴权核心，提供 JWT 中间件、权限检查器与角色管理器。

功能

• JWT 认证中间件（解析 Bearer Token，注入用户上下文）
• 基于 Casbin 的 RBAC 权限引擎（角色→资源→操作）
• Ent ORM 适配器持久化 Casbin 规则
• 角色分配、权限检查、策略管理 API

快速开始

初始化鉴权核心

import frameAuth "github.com/leeforge/framework/auth"

core, err := frameAuth.Setup(ctx, frameAuth.Config{
    DatabaseURL: "postgres://...",
    AutoMigrate: true,   // 自动迁移 CasbinRule 表
    EnableCache: true,   // 启用策略缓存（提升性能）
})

注册 JWT 中间件

r := chi.NewRouter()
r.Use(core.AuthMiddleware())

// 受保护路由
r.Group(func(r chi.Router) {
    r.Get("/users", listUsersHandler)
})

权限检查

// 检查用户是否对某域内资源有操作权限
allowed, err := core.CheckUserPermission(ctx, userID, domain, resource, action)

// 为用户分配角色
err = core.AssignRole(ctx, userID, domain, "editor")

// 为角色授予权限
err = core.GrantPermission(ctx, domain, "editor", "articles", "write")

配置项

type Config struct {
    DatabaseURL string // Casbin 策略存储数据库 URL
    AutoMigrate bool   // 是否自动迁移 casbin_rules 表
    EnableCache bool   // 是否启用内存策略缓存
    JWTSecret   string // JWT 签名密钥
    JWTExpiry   time.Duration // Token 过期时间
}

中间件执行流程

请求 → JWT 验证 → 解析用户ID/域 → Casbin 策略检查 → 通过 → 继续
                                                       ↓ 拒绝 → 401/403

注意事项

• 所有权限决策必须通过此模块，禁止在 handler 中硬编码权限逻辑
• CasbinRule 实体由框架管理，业务层通过 AuthCore API 操作策略，不要直接操作该表
• 策略变更后缓存会自动失效（若启用 EnableCache）

Documentation

Index

• func AuthMiddlewareChain(config AuthConfig, store APIKeyStore, jwtSecret string, logger *zap.Logger) func(next http.Handler) http.Handler
• func RegisterAuthRoutes(router chi.Router, authMiddleware *UnifiedAuthMiddleware)
• type ABACManager
• type ABACMiddleware
  • func NewABACMiddleware(abacManager ABACManager, logger *zap.Logger) *ABACMiddleware
  • func (a *ABACMiddleware) Middleware(resource string, action string, resourceAttrs map[string]interface{}) func(next http.Handler) http.Handler
• type APIKeyInfo
  • func GetUserInfoFromContext(ctx context.Context) (userID string, keyInfo *APIKeyInfo, filters map[string]interface{})
• type APIKeyStore
• type AuthConfig
• type AuthCore
  • func Setup(ctx context.Context, cfg Config) (*AuthCore, error)
  • func (ac *AuthCore) AssignRoleToUser(ctx context.Context, userUUID string, roleCode string, domain string) error
  • func (ac *AuthCore) CheckUserPermission(ctx context.Context, userUUID string, domain string, resource string, ...) (bool, error)
  • func (ac *AuthCore) Close() error
  • func (ac *AuthCore) GetUserRoles(ctx context.Context, userUUID string, domain string) ([]*rbac.Role, error)
• type AuthMiddleware
  • func NewAuthMiddleware(config AuthConfig, store APIKeyStore, jwtSecret string, logger *zap.Logger) *AuthMiddleware
  • func (a *AuthMiddleware) Middleware(next http.Handler) http.Handler
• type Config
• type DataFilterMiddleware
  • func NewDataFilterMiddleware(logger *zap.Logger) *DataFilterMiddleware
  • func (d *DataFilterMiddleware) Middleware(next http.Handler) http.Handler
• type JWTValidator
• type Permission
• type RBACManager
• type RBACMiddleware
  • func NewRBACMiddleware(rbacManager RBACManager, logger *zap.Logger) *RBACMiddleware
  • func (r *RBACMiddleware) Middleware(domain string, resource string, action string) func(next http.Handler) http.Handler
• type RateLimitConfig
• type UnifiedAuthMiddleware
  • func NewUnifiedAuthMiddleware(config AuthConfig, apiKeyStore APIKeyStore, rbacManager RBACManager, ...) *UnifiedAuthMiddleware
  • func (u *UnifiedAuthMiddleware) Middleware(next http.Handler) http.Handler
  • func (u *UnifiedAuthMiddleware) WithABAC(resource, action string, resourceAttrs map[string]interface{}) func(next http.Handler) http.Handler
  • func (u *UnifiedAuthMiddleware) WithDataFilter() func(next http.Handler) http.Handler
  • func (u *UnifiedAuthMiddleware) WithRBAC(resource, action string) func(next http.Handler) http.Handler

Functions

func AuthMiddlewareChain

func AuthMiddlewareChain(config AuthConfig, store APIKeyStore, jwtSecret string, logger *zap.Logger) func(next http.Handler) http.Handler

AuthMiddlewareChain 认证中间件链

func RegisterAuthRoutes

func RegisterAuthRoutes(router chi.Router, authMiddleware *UnifiedAuthMiddleware)

RegisterAuthRoutes 注册认证相关路由

Types

type ABACManager

type ABACManager interface {
	CheckPermission(
		ctx context.Context,
		userAttrs map[string]interface{},
		resourceAttrs map[string]interface{},
		action string,
		contextAttrs map[string]interface{},
	) (bool, error)
}

ABACManager ABAC 管理器接口

type ABACMiddleware

type ABACMiddleware struct {
	// contains filtered or unexported fields
}

ABACMiddleware ABAC 中间件

func NewABACMiddleware

func NewABACMiddleware(abacManager ABACManager, logger *zap.Logger) *ABACMiddleware

NewABACMiddleware 创建 ABAC 中间件

func (*ABACMiddleware) Middleware

func (a *ABACMiddleware) Middleware(resource string, action string, resourceAttrs map[string]interface{}) func(next http.Handler) http.Handler

Middleware ABAC 中间件

type APIKeyInfo

type APIKeyInfo struct {
	Key         string                 `json:"key"`
	CreatedBy   string                 `json:"created_by"`
	ExpiredAt   time.Time              `json:"expired_at"`
	Permissions []Permission           `json:"permissions"`
	DataFilters map[string]interface{} `json:"data_filters"`
	RateLimit   RateLimitConfig        `json:"rate_limit"`
}

APIKeyInfo API Key 信息

func GetUserInfoFromContext

func GetUserInfoFromContext(ctx context.Context) (userID string, keyInfo *APIKeyInfo, filters map[string]interface{})

GetUserInfoFromContext 从上下文获取用户信息

type APIKeyStore

type APIKeyStore interface {
	GetByKey(ctx context.Context, key string) (*APIKeyInfo, error)
	Validate(ctx context.Context, key string) error
}

APIKeyStore API Key 存储接口

type AuthConfig

type AuthConfig struct {
	RequireJWT       bool     // 是否需要 JWT
	RequireAPIKey    bool     // 是否需要 API Key
	EnableDataFilter bool     // 是否启用数据过滤
	AllowedAPIKeys   []string // 允许的 API Key (用于测试)
}

AuthConfig 认证配置

type AuthCore

type AuthCore struct {
	EntClient   *ent.Client
	RBACManager *rbac.RBACManager
	ABACManager *abac.ABACManager
	Adapter     *casbin.EntAdapter
	// contains filtered or unexported fields
}

AuthCore 认证核心实例

func Setup

func Setup(ctx context.Context, cfg Config) (*AuthCore, error)

Setup 初始化 frame-core/auth 包括数据库连接、表迁移、RBAC/ABAC 管理器初始化

func (*AuthCore) AssignRoleToUser

func (ac *AuthCore) AssignRoleToUser(ctx context.Context, userUUID string, roleCode string, domain string) error

AssignRoleToUser 分配角色给用户（快捷方法）

func (*AuthCore) CheckUserPermission

func (ac *AuthCore) CheckUserPermission(
	ctx context.Context,
	userUUID string,
	domain string,
	resource string,
	action string,
) (bool, error)

CheckUserPermission 检查用户权限（快捷方法）

func (*AuthCore) Close

func (ac *AuthCore) Close() error

Close 关闭资源

func (*AuthCore) GetUserRoles

func (ac *AuthCore) GetUserRoles(ctx context.Context, userUUID string, domain string) ([]*rbac.Role, error)

GetUserRoles 获取用户角色（快捷方法）

type AuthMiddleware

type AuthMiddleware struct {
	// contains filtered or unexported fields
}

AuthMiddleware 认证中间件

func NewAuthMiddleware

func NewAuthMiddleware(config AuthConfig, store APIKeyStore, jwtSecret string, logger *zap.Logger) *AuthMiddleware

NewAuthMiddleware 创建认证中间件

func (*AuthMiddleware) Middleware

func (a *AuthMiddleware) Middleware(next http.Handler) http.Handler

Middleware 认证中间件

type Config

type Config struct {
	DatabaseURL string      // 数据库连接 URL
	AutoMigrate bool        // 是否自动迁移数据库
	EnableCache bool        // 是否启用缓存
	Logger      *zap.Logger // 日志记录器
}

Config frame-core/auth 初始化配置

type DataFilterMiddleware

type DataFilterMiddleware struct {
	// contains filtered or unexported fields
}

DataFilterMiddleware 数据过滤中间件

func NewDataFilterMiddleware

func NewDataFilterMiddleware(logger *zap.Logger) *DataFilterMiddleware

NewDataFilterMiddleware 创建数据过滤中间件

func (*DataFilterMiddleware) Middleware

func (d *DataFilterMiddleware) Middleware(next http.Handler) http.Handler

Middleware 数据过滤中间件

type JWTValidator

type JWTValidator interface {
	Validate(token string) (string, error) // 返回 userID
}

JWTValidator JWT 验证器接口

type Permission

type Permission struct {
	Resource string `json:"resource"`
	Action   string `json:"action"`
}

Permission 权限

type RBACManager

type RBACManager interface {
	CheckPermission(ctx context.Context, userUUID, domain, resource, action string) (bool, error)
}

RBACManager RBAC 管理器接口

type RBACMiddleware

type RBACMiddleware struct {
	// contains filtered or unexported fields
}

RBACMiddleware RBAC 中间件

func NewRBACMiddleware

func NewRBACMiddleware(rbacManager RBACManager, logger *zap.Logger) *RBACMiddleware

NewRBACMiddleware 创建 RBAC 中间件

func (*RBACMiddleware) Middleware

func (r *RBACMiddleware) Middleware(domain string, resource string, action string) func(next http.Handler) http.Handler

Middleware RBAC 中间件

type RateLimitConfig

type RateLimitConfig struct {
	Minute int `json:"minute"`
	Daily  int `json:"daily"`
	Burst  int `json:"burst"`
}

RateLimitConfig 限流配置

type UnifiedAuthMiddleware

type UnifiedAuthMiddleware struct {
	// contains filtered or unexported fields
}

UnifiedAuthMiddleware 统一认证中间件

func NewUnifiedAuthMiddleware

func NewUnifiedAuthMiddleware(
	config AuthConfig,
	apiKeyStore APIKeyStore,
	rbacManager RBACManager,
	abacManager ABACManager,
	logger *zap.Logger,
) *UnifiedAuthMiddleware

NewUnifiedAuthMiddleware 创建统一认证中间件

func (*UnifiedAuthMiddleware) Middleware

func (u *UnifiedAuthMiddleware) Middleware(next http.Handler) http.Handler

Middleware 统一认证中间件

func (*UnifiedAuthMiddleware) WithABAC

func (u *UnifiedAuthMiddleware) WithABAC(resource, action string, resourceAttrs map[string]interface{}) func(next http.Handler) http.Handler

WithABAC 添加 ABAC 检查

func (*UnifiedAuthMiddleware) WithDataFilter

func (u *UnifiedAuthMiddleware) WithDataFilter() func(next http.Handler) http.Handler

WithDataFilter 添加数据过滤

func (*UnifiedAuthMiddleware) WithRBAC

func (u *UnifiedAuthMiddleware) WithRBAC(resource, action string) func(next http.Handler) http.Handler

WithRBAC 添加 RBAC 检查