OneAuth.Client.AspNetCore 0.4.0

OneAuth.Client.AspNetCore

OneAuth 统一身份权限中心的 ASP.NET Core 业务系统接入 SDK。

• 按用户有效权限注水：验签后由 PermissionClaimsTransformer 把用户在本系统的有效权限（直接授权 ∪ 角色授权，中心物化）以 permissions claim 注入 ClaimsPrincipal，FastEndpoints 的 Permissions(...) / 标准授权检查照常工作，业务代码零改动。
• EffectivePermissionCache：IMemoryCache TTL 缓存（默认 2 分钟）+ Redis perm-invalidate 精确失效 + 中心不可达时沿用过期缓存（stale-while-error）。
• 权限树契约接口：MapOneAuthPermissionContract 暴露本系统权限点树，供权限中心拉取同步。
• 约定式接入：AddOneAuthJwtBearer() + AddOneAuthEffectivePermissions() 两行完成，配置从 OneAuth 节读取。

安装

dotnet add package OneAuth.Client.AspNetCore

目标框架：net10.0。

快速接入

1. 配置（appsettings.json）

{
  "OneAuth": {
    "Keycloak": {
      "Authority": "http://localhost:8080/realms/corp",
      "Audience": "asset-admin",
      "TokenUrl": "http://localhost:8080/realms/corp/protocol/openid-connect/token",
      "ClientId": "asset-admin-svc",
      "ClientSecret": "asset-admin-svc-secret"
    },
    "PermissionCenter": {
      "Url": "http://localhost:5511",
      "Redis": "localhost:6379"
    }
  }
}

2. 注册（Program.cs）

var builder = WebApplication.CreateBuilder(args);

builder.AddOneAuthJwtBearer();   // JWT 验签（MapInboundClaims=false 由 SDK 固定）
builder.AddOneAuthEffectivePermissions(); // 有效权限缓存 + claims 注水

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

// 可选：暴露权限树契约接口，供权限中心拉取本系统权限点
// （配置了 OneAuth:PermissionCenter:ContractKey 时要求请求头 X-OneAuth-Contract-Key 匹配）
app.MapOneAuthPermissionContract(tree);

app.Run();

之后端点上直接声明权限点即可（FastEndpoints 示例）：

public class ExportEndpoint : EndpointWithoutRequest
{
    public override void Configure()
    {
        Post("/api/assets/export");
        Permissions("assets.export");
    }
}

工作原理

JWT 验签通过
   │
   ▼
PermissionClaimsTransformer  ──► 读 sub
   │
   ▼
EffectivePermissionCache.GetAsync(userId)
   │  命中 IMemoryCache（TTL 默认 2min）──► 直接返回
   │  未命中 ──► client_credentials 换 token
   │          ──► GET {中心}/api/systems/{systemId}/users/{userId}/permissions
   │          ──► 中心不可达：沿用最后一次成功值（stale-while-error）
   ▼
权限点以 "permissions" claim 注入 ClaimsPrincipal
   │
   ▼
FastEndpoints Permissions(...) / 标准授权检查

权限变更即时生效：权限中心重算物化权限后向 Redis perm-invalidate 频道广播，SDK 后台服务收到通知后精确失效对应用户的本地缓存（systemId 匹配或 * 全量）。

手动失效

需要时可注入 EffectivePermissionCache 主动失效：

cache.Invalidate(userId);  // 精确失效某用户
cache.InvalidateAll();     // 清空本系统全部条目（不影响宿主应用其他缓存）

systemId 缺省取 OneAuth:Keycloak:Audience，也可显式传入：builder.AddOneAuthEffectivePermissions("my-system")。

License

MIT