feat: add scoped tenant api keys

This commit is contained in:
wizardchen
2026-07-05 10:25:37 +08:00
committed by lyingbug
parent 1708d6895a
commit 505bc7ddec
49 changed files with 2899 additions and 1578 deletions
+149
View File
@@ -0,0 +1,149 @@
package middleware
import (
"context"
stderrors "errors"
"net/http"
"strings"
"github.com/Tencent/WeKnora/internal/types"
)
var errTenantAPIKeyScopeForbidden = stderrors.New("tenant api key scope forbidden")
func authorizeTenantAPIKeyOperation(ctx context.Context, method string) error {
if _, ok := types.TenantAPIKeyScopeFromContext(ctx); !ok {
return nil
}
return nil
}
func authorizeTenantAPIKeyRoute(ctx context.Context, method, path string) error {
scope, ok := types.TenantAPIKeyScopeFromContext(ctx)
if !ok {
return nil
}
if strings.Contains(path, "/api-keys") {
return errTenantAPIKeyScopeForbidden
}
if isSafeHTTPMethod(method) {
if allowsTenantAPIKeyRead(scope) {
return nil
}
return errTenantAPIKeyScopeForbidden
}
if isTenantAPIKeyReadUnsafePath(method, path) && allowsTenantAPIKeyRead(scope) {
return nil
}
if isKnowledgeScopedUnsafePath(path) && allowsTenantAPIKeyWrite(scope) {
return nil
}
if allowsTenantAPIKeyAdmin(scope) {
return nil
}
return errTenantAPIKeyScopeForbidden
}
func authorizeTenantAPIKeyKnowledgeBase(ctx context.Context, kbID string) error {
scope, ok := types.TenantAPIKeyScopeFromContext(ctx)
if !ok {
return nil
}
if scope.AllowsKnowledgeBase(kbID) {
return nil
}
return errTenantAPIKeyScopeForbidden
}
func isSafeHTTPMethod(method string) bool {
switch method {
case http.MethodGet, http.MethodHead, http.MethodOptions:
return true
default:
return false
}
}
func isKnowledgeScopedUnsafePath(path string) bool {
denyPrefixes := []string{
"/api/v1/knowledge-bases/copy",
"/api/v1/knowledge/tags",
"/api/v1/knowledge/batch-reparse",
"/api/v1/knowledge/batch-delete",
"/api/v1/knowledge/move",
}
for _, prefix := range denyPrefixes {
if path == prefix || strings.HasPrefix(path, prefix+"/") {
return false
}
}
if path == "/api/v1/sessions" {
return true
}
allowPrefixes := []string{
"/api/v1/knowledge-bases/",
"/api/v1/knowledge/",
"/api/v1/chunks/",
"/api/v1/knowledgebase/",
"/api/v1/knowledge-search",
"/api/v1/knowledge-chat/",
}
for _, prefix := range allowPrefixes {
if path == prefix || strings.HasPrefix(path, prefix) {
return true
}
}
return false
}
func allowsTenantAPIKeyRead(scope types.TenantAPIKeyScope) bool {
scope = scope.Normalize()
return len(scope.Scopes) == 0 ||
scope.HasScope(types.TenantAPIKeyScopeRead) ||
scope.HasScope(types.TenantAPIKeyScopeWrite) ||
scope.HasScope(types.TenantAPIKeyScopeAdmin)
}
func allowsTenantAPIKeyWrite(scope types.TenantAPIKeyScope) bool {
scope = scope.Normalize()
return len(scope.Scopes) == 0 ||
scope.HasScope(types.TenantAPIKeyScopeWrite) ||
scope.HasScope(types.TenantAPIKeyScopeAdmin)
}
func allowsTenantAPIKeyAdmin(scope types.TenantAPIKeyScope) bool {
scope = scope.Normalize()
return len(scope.Scopes) == 0 || scope.HasScope(types.TenantAPIKeyScopeAdmin)
}
func isTenantAPIKeyReadUnsafePath(method, path string) bool {
if method != http.MethodPost {
return false
}
if path == "/api/v1/sessions" ||
path == "/api/v1/knowledge-search" ||
path == "/api/v1/messages/search" ||
path == "/api/v1/chunker/preview" {
return true
}
readPrefixes := []string{
"/api/v1/knowledge-chat/",
"/api/v1/agent-chat/",
}
for _, prefix := range readPrefixes {
if strings.HasPrefix(path, prefix) {
return true
}
}
readSuffixes := []string{
"/hybrid-search",
"/faq/search",
}
for _, suffix := range readSuffixes {
if strings.HasSuffix(path, suffix) {
return true
}
}
return false
}
+123
View File
@@ -0,0 +1,123 @@
package middleware
import (
"context"
stderrors "errors"
"net/http"
"testing"
"github.com/Tencent/WeKnora/internal/types"
)
func TestTenantAPIKeyScopeReadOnlyAllowsSafeMethods(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeRead},
})
if err := authorizeTenantAPIKeyOperation(ctx, http.MethodGet); err != nil {
t.Fatalf("read scoped key should allow GET: %v", err)
}
if err := authorizeTenantAPIKeyOperation(ctx, http.MethodHead); err != nil {
t.Fatalf("read scoped key should allow HEAD: %v", err)
}
}
func TestTenantAPIKeyScopeReadOnlyRejectsUnsafeMethods(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeRead},
})
if err := authorizeTenantAPIKeyRoute(ctx, http.MethodPost, "/api/v1/knowledge-bases/kb-1/knowledge/file"); !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("read scoped key POST error = %v, want errTenantAPIKeyScopeForbidden", err)
}
}
func TestTenantAPIKeyScopeReadOnlyAllowsSemanticReadPost(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeRead},
})
if err := authorizeTenantAPIKeyRoute(ctx, http.MethodPost, "/api/v1/knowledge-search"); err != nil {
t.Fatalf("read scoped key should allow semantic read POST: %v", err)
}
}
func TestTenantAPIKeyScopeAllowsScopedKnowledgeBase(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
KnowledgeBaseIDs: types.StringArray{"kb-1"},
})
if err := authorizeTenantAPIKeyKnowledgeBase(ctx, "kb-1"); err != nil {
t.Fatalf("key scoped to kb-1 should allow kb-1: %v", err)
}
if err := authorizeTenantAPIKeyKnowledgeBase(ctx, "kb-2"); !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("key scoped to kb-1 should reject kb-2, got %v", err)
}
}
func TestTenantAPIKeyRouteRejectsAPIKeyManagement(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeAdmin},
})
err := authorizeTenantAPIKeyRoute(ctx, http.MethodPost, "/api/v1/tenants/1/api-keys")
if !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("api key management error = %v, want errTenantAPIKeyScopeForbidden", err)
}
}
func TestTenantAPIKeyRouteRejectsTenantWriteForKnowledgeRestrictedKey(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeWrite},
KnowledgeBaseIDs: types.StringArray{"kb-1"},
})
err := authorizeTenantAPIKeyRoute(ctx, http.MethodPut, "/api/v1/tenants/kv/theme")
if !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("tenant write error = %v, want errTenantAPIKeyScopeForbidden", err)
}
}
func TestTenantAPIKeyRouteRejectsTenantWriteForWriteScope(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeWrite},
})
err := authorizeTenantAPIKeyRoute(ctx, http.MethodPut, "/api/v1/tenants/1")
if !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("tenant write error = %v, want errTenantAPIKeyScopeForbidden", err)
}
}
func TestTenantAPIKeyRouteAllowsTenantWriteForAdminScope(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeAdmin},
})
if err := authorizeTenantAPIKeyRoute(ctx, http.MethodPut, "/api/v1/tenants/kv/theme"); err != nil {
t.Fatalf("admin scoped key should allow tenant management route: %v", err)
}
}
func TestTenantAPIKeyRouteAllowsKnowledgeWriteForKnowledgeRestrictedKey(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeWrite},
KnowledgeBaseIDs: types.StringArray{"kb-1"},
})
if err := authorizeTenantAPIKeyRoute(ctx, http.MethodPut, "/api/v1/knowledge-bases/kb-1"); err != nil {
t.Fatalf("scoped knowledge write should pass route layer: %v", err)
}
}
func TestTenantAPIKeyRouteRejectsCrossKnowledgeBatchWriteForKnowledgeRestrictedKey(t *testing.T) {
ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{
Scopes: types.StringArray{types.TenantAPIKeyScopeWrite},
KnowledgeBaseIDs: types.StringArray{"kb-1"},
})
err := authorizeTenantAPIKeyRoute(ctx, http.MethodPost, "/api/v1/knowledge/batch-delete")
if !stderrors.Is(err, errTenantAPIKeyScopeForbidden) {
t.Fatalf("batch write error = %v, want errTenantAPIKeyScopeForbidden", err)
}
}
+110 -82
View File
@@ -2,7 +2,6 @@ package middleware
import (
"context"
"crypto/subtle"
"encoding/json"
"errors"
"fmt"
@@ -83,6 +82,7 @@ func Auth(
tenantService interfaces.TenantService,
userService interfaces.UserService,
memberService interfaces.TenantMemberService,
apiKeyService interfaces.TenantAPIKeyService,
cfg *config.Config,
) gin.HandlerFunc {
return func(c *gin.Context) {
@@ -211,92 +211,60 @@ func Auth(
// 尝试X-API-Key认证(兼容模式)
apiKey := c.GetHeader("X-API-Key")
if apiKey != "" {
// Get tenant information
tenantID, err := tenantService.ExtractTenantIDFromAPIKey(apiKey)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"error": "Unauthorized: invalid API key format",
})
c.Abort()
return
}
// Verify API key validity (matches the one in database)
t, err := tenantService.GetTenantByID(c.Request.Context(), tenantID)
if err != nil {
log.Printf("Error getting tenant by ID: %v, tenantID: %d", err, tenantID)
c.JSON(http.StatusUnauthorized, gin.H{
"error": "Unauthorized: invalid API key",
})
c.Abort()
return
}
if t == nil || subtle.ConstantTimeCompare([]byte(t.APIKey), []byte(apiKey)) != 1 {
c.JSON(http.StatusUnauthorized, gin.H{
"error": "Unauthorized: invalid API key",
})
c.Abort()
return
}
// 存储租户和用户信息到上下文
c.Set(types.TenantIDContextKey.String(), tenantID)
c.Set(types.TenantInfoContextKey.String(), t)
ctx := context.WithValue(
context.WithValue(c.Request.Context(), types.TenantIDContextKey, tenantID),
types.TenantInfoContextKey, t,
)
// 通过 TenantID 关联查询用户;找不到时构造系统虚拟用户,
// 确保所有依赖 UserContextKey 的下游 handler 正常工作。
user, err := userService.GetUserByTenantID(c.Request.Context(), tenantID)
if err != nil || user == nil {
// Synthetic user. The "system-<tenantID>" shape is recognised
// by types.IsSyntheticUserID, which RBAC service-layer code
// uses to skip recording these IDs as a resource creator.
// Do NOT change the prefix or numeric suffix without
// updating that helper, otherwise KB/Agent CreatorID will
// silently start pointing at the synthetic user again.
user = &types.User{
ID: fmt.Sprintf("system-%d", tenantID),
Username: fmt.Sprintf("system-%d", tenantID),
Email: fmt.Sprintf("system-%d@api-key.local", tenantID),
TenantID: tenantID,
IsActive: true,
if apiKeyService != nil {
if key, err := apiKeyService.AuthenticateAPIKey(c.Request.Context(), apiKey); err == nil && key != nil {
attachAPIKeyAuthContext(c, tenantService, userService, key.TenantID, key)
if c.IsAborted() {
return
}
if err := authorizeTenantAPIKeyOperation(c.Request.Context(), c.Request.Method); err != nil {
c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden: API key scope does not allow this operation"})
c.Abort()
return
}
if err := authorizeTenantAPIKeyRoute(c.Request.Context(), c.Request.Method, c.Request.URL.Path); err != nil {
c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden: API key scope does not allow this route"})
c.Abort()
return
}
c.Next()
return
}
log.Printf("No user found for tenant %d via API key, using synthetic system user %s", tenantID, user.ID)
}
// API-Key 走的是程序化全租户访问,固定授予 Admin 角色:可以做几乎所有事情,
// 但保留 Owner-only 操作(删除租户、修改租户级配置)的边界。
//
// 显式拒绝 SystemAdmin:API key 通常被存放在 CI / IaC / sidecar 里,
// 泄露面比 JWT 大得多。即便 key 关联的 user 在 DB 里恰好是 SystemAdmin
// (例如部署里只有一个用户、自己创建了 tenant 又生成了 API key),
// 也绝不允许通过这条通道走平台级管理操作(promote/revoke、全局设置)。
// 平台管理必须走交互式 JWT 登录,留下可追责的人类身份。
c.Set(types.UserContextKey.String(), user)
c.Set(types.UserIDContextKey.String(), user.ID)
principal, principalErr := resolveAPIPrincipal(c.Request.Context(), t, c.Request.Header)
if principalErr != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"error": apiPrincipalAuthErrorMessage(principalErr),
})
tenantID, err := tenantService.ExtractTenantIDFromAPIKey(apiKey)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{
"error": "Unauthorized: invalid API key format",
})
c.Abort()
return
}
if key, err := apiKeyService.AuthenticateTenantAPIKey(
c.Request.Context(), tenantID, apiKey,
); err == nil && key != nil {
attachAPIKeyAuthContext(c, tenantService, userService, tenantID, key)
if c.IsAborted() {
return
}
if err := authorizeTenantAPIKeyOperation(c.Request.Context(), c.Request.Method); err != nil {
c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden: API key scope does not allow this operation"})
c.Abort()
return
}
if err := authorizeTenantAPIKeyRoute(c.Request.Context(), c.Request.Method, c.Request.URL.Path); err != nil {
c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden: API key scope does not allow this route"})
c.Abort()
return
}
c.Next()
return
}
c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized: invalid API key"})
c.Abort()
return
}
c.Set(types.PrincipalContextKey.String(), principal)
c.Set(types.TenantRoleContextKey.String(), types.TenantRoleAdmin)
c.Set(types.SystemAdminContextKey.String(), false)
ctx = context.WithValue(ctx, types.UserContextKey, user)
ctx = context.WithValue(ctx, types.UserIDContextKey, user.ID)
ctx = types.WithPrincipal(ctx, principal)
ctx = context.WithValue(ctx, types.TenantRoleContextKey, types.TenantRoleAdmin)
ctx = context.WithValue(ctx, types.SystemAdminContextKey, false)
c.Request = c.Request.WithContext(ctx)
c.Next()
c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized: API key service is not configured"})
c.Abort()
return
}
@@ -306,6 +274,66 @@ func Auth(
}
}
func attachAPIKeyAuthContext(
c *gin.Context,
tenantService interfaces.TenantService,
userService interfaces.UserService,
tenantID uint64,
key *types.TenantAPIKey,
) {
t, err := tenantService.GetTenantByID(c.Request.Context(), tenantID)
if err != nil {
log.Printf("Error getting tenant by ID: %v, tenantID: %d", err, tenantID)
c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized: invalid API key"})
c.Abort()
return
}
c.Set(types.TenantIDContextKey.String(), tenantID)
c.Set(types.TenantInfoContextKey.String(), t)
ctx := context.WithValue(
context.WithValue(c.Request.Context(), types.TenantIDContextKey, tenantID),
types.TenantInfoContextKey, t,
)
user, err := userService.GetUserByTenantID(c.Request.Context(), tenantID)
if err != nil || user == nil {
user = &types.User{
ID: fmt.Sprintf("system-%d", tenantID),
Username: fmt.Sprintf("system-%d", tenantID),
Email: fmt.Sprintf("system-%d@api-key.local", tenantID),
TenantID: tenantID,
IsActive: true,
}
log.Printf("No user found for tenant %d via API key, using synthetic system user %s", tenantID, user.ID)
}
c.Set(types.UserContextKey.String(), user)
c.Set(types.UserIDContextKey.String(), user.ID)
principal, principalErr := resolveAPIPrincipal(c.Request.Context(), t, c.Request.Header)
if principalErr != nil {
c.JSON(http.StatusUnauthorized, gin.H{"error": apiPrincipalAuthErrorMessage(principalErr)})
c.Abort()
return
}
c.Set(types.PrincipalContextKey.String(), principal)
c.Set(types.TenantRoleContextKey.String(), types.TenantRoleAdmin)
c.Set(types.SystemAdminContextKey.String(), false)
ctx = context.WithValue(ctx, types.UserContextKey, user)
ctx = context.WithValue(ctx, types.UserIDContextKey, user.ID)
ctx = types.WithPrincipal(ctx, principal)
ctx = context.WithValue(ctx, types.TenantRoleContextKey, types.TenantRoleAdmin)
ctx = context.WithValue(ctx, types.SystemAdminContextKey, false)
if key != nil {
ctx = types.WithTenantAPIKeyScope(ctx, types.TenantAPIKeyScope{
KeyID: key.ID,
Scopes: key.Scopes,
KnowledgeBaseIDs: key.KnowledgeBaseIDs,
})
}
c.Request = c.Request.WithContext(ctx)
}
func resolveAPIPrincipal(ctx context.Context, tenant *types.Tenant, header http.Header) (types.Principal, error) {
tenantID := uint64(0)
if tenant != nil {
+5
View File
@@ -241,6 +241,11 @@ func RequireKBAccess(
}
ctx := c.Request.Context()
if err := authorizeTenantAPIKeyKnowledgeBase(ctx, kbID); err != nil {
_ = c.Error(apperrors.NewForbiddenError("API key scope does not allow this knowledge base"))
c.Abort()
return
}
// Rollout window: enforcement off -> log the would-be check and
// pass through. We still resolve the KB (best-effort) so the