跳到主要内容
版本：0.4.x(Latest)

基本介绍​

services.Auth()返回认证与授权命名空间。源码插件通过services.Auth()访问，动态插件通过plugin.yaml声明service: auth后使用pluginbridge.Default().Auth()客户端访问。它包含两个子能力：

  • Token()处理租户令牌选择、租户切换和平台管理员模拟令牌交接；
  • Authz()处理权限视图读取、权限判断和平台管理员判断。

该命名空间不暴露宿主JWT签名实现、会话存储、角色表、菜单表或权限表。插件只通过稳定领域契约发起令牌或授权相关操作。

能力阶段：运行期

类型支持：源码插件、动态插件

能力设计​

子能力体系​

Auth能力采用双子能力模式，分别处理认证令牌和授权判断：

Token子能力​

Token()负责租户令牌交接，处理宿主签名、令牌ID、在线会话状态和权限缓存预热。插件在调用前仍需完成业务授权和审计检查。

Authz子能力​

Authz()负责授权判断，只返回插件可见视图或布尔结果，不暴露宿主角色、菜单或权限表结构。可信源码插件如需替换角色权限集合，应使用services.Admin().Auth().Authz().ReplaceRolePermissions。

动态插件身份获取​

动态插件通过plugin.yaml声明service: auth后，使用pluginbridge.Default().Auth()客户端访问Token()子能力。动态路由请求的认证结果同时也由宿主注入BridgeRequestEnvelopeV1.Identity。

接口定义​

Token子能力接口​

方法说明
SelectTenant消费预登录PreToken，签发绑定目标租户的AccessToken和RefreshToken
SwitchTenant校验目标租户成员关系，撤销当前令牌并签发新租户令牌
IssueImpersonationToken为平台管理员签发进入目标租户的模拟令牌
RevokeImpersonationToken校验并撤销模拟访问令牌

Authz子能力接口​

方法说明
BatchGetPermissions批量读取可见权限视图，缺失结果不透露具体原因
HasPermission判断当前操作者在当前范围内是否拥有指定权限
IsPlatformAdmin判断指定用户是否拥有平台全量数据角色

动态插件接口​

动态插件通过hostServices.auth声明授权的方法：

动态方法说明
tenant.select消费预登录PreToken，签发绑定目标租户的令牌
tenant.switch校验目标租户成员关系，撤销当前令牌并签发新租户令牌
impersonation_token.issue为平台管理员签发进入目标租户的模拟令牌
impersonation_token.revoke校验并撤销模拟访问令牌

能力使用​

源码插件使用​

源码插件通过services.Auth()访问Token()和Authz()子能力：

// 租户选择：签发绑定目标租户的令牌
tenantToken, err := services.Auth().Token().SelectTenant(ctx, token.SelectTenantInput{
    PreToken: preToken,
    TenantID: tenantID,
})

// 租户切换：校验成员关系并签发新令牌
tenantToken, err = services.Auth().Token().SwitchTenant(ctx, token.SwitchTenantInput{
    BearerToken: bearerToken,
    TenantID:    targetTenantID,
})

// 权限判断
has, err := services.Auth().Authz().HasPermission(ctx, capabilityCtx, permissionKey)

// 平台管理员判断
isAdmin, err := services.Auth().Authz().IsPlatformAdmin(ctx, capabilityCtx, userID)

可信源码插件如需替换角色权限集合：

err := services.Admin().Auth().Authz().ReplaceRolePermissions(ctx, capabilityCtx, roleID, permissions)

动态插件使用​

动态插件在plugin.yaml中声明auth服务和授权方法：

hostServices:
  - service: auth
    methods:
      - tenant.select
      - tenant.switch

动态插件通过pluginbridge.Default().Auth()客户端调用：

authSvc := pluginbridge.Default().Auth()

// 租户选择：签发绑定目标租户的令牌
tenantToken, err := authSvc.Token().SelectTenant(ctx, token.SelectTenantInput{
    PreToken: preToken,
    TenantID: tenantID,
})

// 租户切换：校验成员关系并签发新令牌
tenantToken, err = authSvc.Token().SwitchTenant(ctx, token.SwitchTenantInput{
    BearerToken: bearerToken,
    TenantID:    targetTenantID,
})

设计约束​

  • 插件不直接签发JWT。 签名、密钥、过期策略和会话注册由宿主认证服务统一控制。
  • 租户切换必须经过校验。 SwitchTenant会校验成员关系并撤销旧令牌，客户端必须使用新令牌继续请求。
  • 授权读取不暴露权限表。 Authz()只返回插件可见视图或布尔结果，不暴露宿主角色、菜单或权限表结构。
  • 模拟令牌需要调用方审计。 插件应记录谁在什么原因下模拟进入哪个租户。

相关服务​