IdentityLinker.Configuration.EntityFrameworkCore 3.0.0-preview.2

IdentityLinker

IdentityLinker 是面向 .NET 10 的身份框架，当前版本为 3.0.0-preview.2。它以 IdentityServer4 的公开使用体验为兼容基线，OAuth/OIDC 与 SAML 协议引擎依据公开标准独立实现，并使用 ASP.NET Core、Microsoft.IdentityModel、.NET 密码学/XML 基础设施与 YARP 承载平台能力。

当前实现状态和逐项验收矩阵见仓库根目录的 IMPLEMENTATION_PLAN.md。

结构化产品契约从 IdentityLinker 产品域文档 进入；仓库级索引由 docs/product-domains/catalog.md 生成。

设计目标

• OAuth 2.x、OpenID Connect、SAML 2.0、DCR、DPoP、mTLS、CIBA、FAPI 配置评估与 BFF。
• IdentityServer4 风格的简洁 fluent API。
• 存储、验证、声明、密钥、会话、事件和协议交互均可替换。
• 生产环境安全失败；开发凭据不会自动进入 Production。
• 发布包及其依赖图只包含本仓库实现与已列明的第三方基础库。

CIBA 交付边界

Development 环境可使用默认内存状态验证 CIBA poll；生产环境启用 CIBA 时必须同时配置 ICibaDurableRequestStore、跨节点原子限流存储以及共享且可轮换的限流 HMAC 密钥。ping 在 Development 可使用默认可租约内存 outbox；生产环境只有同一持久化实现同时承担 durable request store、ICibaPingDecisionOutboxStore、通知 outbox/reader 和可恢复租约时才会开放，以保证用户决策、加密通知任务和关联幂等键在同一事务中提交。push 默认安全拒绝；显式调用 AddDefaultCibaPushTokenResponseGenerator() 或注册满足同一 durable issuance journal/commit store 的 generator 后，才会在 readiness 完整时开放。该边界包含受保护固定响应、operation/idempotency 幂等、租约/fencing、崩溃对账、重试/dead-letter，以及 token 记录、request、job 和 notification outbox 的原子提交。未满足这些条件时，请求会明确返回 invalid_request，发现文档不会宣称支持对应模式。

AddCibaPushTokenResponseWorker<TWorker>() 是旧的应用自定义 worker 扩展，单独注册不会改变 push 可用性；内置实现使用 AddDefaultCibaPushTokenResponseGenerator()，只有在 token response 已写入可靠 outbox 并完成原子对账后才会开放 push。

最小入口

默认场景可安装聚合包（当前版本 3.0.0-preview.2）：

dotnet add package IdentityLinker --version 3.0.0-preview.2

builder.Services.AddIdentityLinker(options =>
{
    options.Issuer = new Uri("https://identity.example.com");
});

var app = builder.Build();
app.UseIdentityLinker();
app.MapIdentityLinkerEndpoints();

动态客户端注册

安装 IdentityLinker.Configuration 后，在同一 fluent builder 上启用 RFC 7591/7592：

builder.Services.AddIdentityLinker(options =>
{
    options.Issuer = new Uri("https://identity.example.com");
})
.AddIdentityLinkerConfiguration(options =>
{
    options.RegistrationEndpointPath = "/connect/register";
});

app.MapIdentityLinkerEndpoints();

默认拒绝没有 initial access token 的注册请求；生产环境必须通过 AddInitialAccessTokenValidator<TValidator>() 注册自有 IInitialAccessTokenValidator，并提供持久化的客户端注册 store 和 registration access token service。

BFF 安全入口

BFF 是独立功能包，先安装：

dotnet add package IdentityLinker.Bff --version 3.0.0-preview.2

BFF 必须显式配置受信任公开源；callback、logout 和代理转发信息不会从请求的 Host、scheme 或 PathBase 推导。部署在反向代理子路径时使用 PublicPathBase：

builder.Services.AddBff(options =>
{
    options.PublicOrigin = new Uri("https://app.example.com");
    options.PublicPathBase = "/portal";
    options.Oidc.Authority = new Uri("https://identity.example.com");
    options.Oidc.ClientId = "portal-bff";
    options.Oidc.ClientSecret = builder.Configuration["Bff:ClientSecret"];
});

EF Core store 对高熵 session handle 使用域分离 SHA-256；对可枚举的 sid、sub 和 logout jti 必须使用持久、可轮换的具名 HMAC 密钥。当前密钥用于写入，历史密钥仅用于查询和撤销旧记录：

builder.Services.AddBff(options =>
{
    options.PublicOrigin = new Uri("https://app.example.com");
    options.Oidc.Authority = new Uri("https://identity.example.com");
    options.Oidc.ClientId = "portal-bff";
    options.Oidc.ClientSecret = builder.Configuration["Bff:ClientSecret"];
})
.AddEntityFrameworkCore<AppDbContext>(store =>
{
    store.ActiveIndexKey = new BffEntityIndexKey(
        "2026-07",
        Convert.FromBase64String(
            builder.Configuration["Bff:IndexKey"] ??
            throw new InvalidOperationException("缺少 BFF 索引密钥。")));
});

索引密钥必须来自 secret manager 或 HSM 注入，至少 32 个随机字节；不得写入源码、日志或普通配置文件。轮换时先把旧密钥加入 PreviousIndexKeys，待所有旧记录自然过期或迁移完成后再移除。

各模块的独立包消费示例位于 tests/IdentityLinker.*.PackageConsumer*，可用于验证只通过 NuGet 包引用时的构建与运行时行为。Entity Framework Core、BFF Entity Framework Core 和 Configuration Entity Framework Core 包不承诺 Native AOT 或 trimming；这些包的持久化验收以 EF Core + SQLite 为准。

从入门到精通的中文学习中心位于 docs/identitylinker/index.md，全场景示例矩阵位于 samples/scenarios.md。BFF 和 Blazor WASM 的真实包消费 fixture 位于 .github/fixtures，不在 tests 目录下。

示例与验证

仓库已提供 Core、SAML、EntityFrameworkCore、JwtBearer、BFF 和 Blazor Client 的包消费与专项回归项目；EntityFrameworkCore 相关验证以 EF Core + SQLite schema、迁移、并发事务、重启和幂等测试为准。示例代码以当前正式 src/ 实现为准，发布前的剩余门禁和最新证据统一记录在 IMPLEMENTATION_PLAN.md。

生产部署检查清单

从 Development 切换到 Production 前，逐项确认：

• Issuer 是公开可访问的绝对 HTTPS URI，不含 query/fragment
• 客户端、资源和状态存储已替换为持久化实现，不再使用 AddInMemory*
• 签名/加密密钥来自受控密钥源，支持轮换，未使用 AddDevelopmentCredentials
• IServerSessionStore 已持久化且支持撤销/重启恢复
• 启用的每个 feature（PAR、Device、CIBA、DCR、DPoP 等）都有对应的持久化 store 和必需配置
• CIBA poll 有 durable request store + 跨节点限流 + 共享可轮换 HMAC key
• CIBA ping 有原子 decision/outbox + 可恢复租约
• CIBA push 有 durable issuance journal + 固定受保护响应 + worker
• DCR 有 IInitialAccessTokenValidator + 持久化 store + RAT service
• DPoP/mTLS 在缺少 proof 时不退化为 bearer
• BFF 的 PublicOrigin 已显式配置为 HTTPS，不依赖请求 Host 推导
• BFF EF 索引密钥来自 secret manager，至少 32 字节，不在源码/日志/配置中明文出现

常见报错与修复