.NET Core 3.1对接Keycloak授权出现Correlation failed错误如何解决

Correlation failed异常解决方案 #

该异常由ASP.NET Core远程身份验证中间件无法匹配认证请求与回调请求的关联Cookie触发，可按以下步骤排查修复： #

1 校验Keycloak客户端配置 #

• 确认Keycloak对应客户端的有效重定向URI已添加API的回调地址，默认回调路径为/signin-oidc，本地开发需配置为https://localhost:<你的API端口>/signin-oidc，生产环境替换为实际域名
• 客户端访问类型为confidential时，需确保代码中配置的ClientSecret与Keycloak客户端配置页的Secret完全一致
• 生产环境不要开启隐式流，使用授权码流即可

2 修正.NET Core 3.1 认证中间件配置 #

标准配置示例如下：

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.IdentityModel.Tokens;

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();

    services.AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        options.Authority = "https://<你的Keycloak域名>/auth/realms/<你的Realm名称>";
        options.ClientId = "<你的Keycloak客户端ID>";
        // public类型客户端无需填写ClientSecret
        options.ClientSecret = "<你的Keycloak客户端Secret>";
        options.ResponseType = "code";
        // 回调路径需和Keycloak配置的重定向URI路径完全一致
        options.CallbackPath = "/signin-oidc";
        // 仅本地开发关闭HTTPS元数据校验，生产环境请删除该行
        options.RequireHttpsMetadata = false;
        // 修复.NET Core 3.1默认SameSite规则导致的关联Cookie丢失问题
        options.NonceCookie.SameSite = SameSiteMode.Unspecified;
        options.CorrelationCookie.SameSite = SameSiteMode.Unspecified;
        options.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType = "name",
            RoleClaimType = "role"
        };
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 反向代理部署时需将UseForwardedHeaders放在最开头，本地开发可注释
    app.UseForwardedHeaders();
    
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseRouting();

    // 注意顺序：先认证再授权
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

• 重点确认Configure方法中中间件顺序：UseAuthentication必须放在UseAuthorization之前，顺序错误会直接导致身份校验失败

3 反向代理部署场景额外配置 #

如果API部署在Nginx、K8s Ingress等反向代理之后，需添加转发头配置让ASP.NET Core识别原始请求协议与地址：

services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    // 生产环境建议替换为实际反向代理IP，不要清空所有校验
    options.KnownProxies.Clear();
    options.KnownNetworks.Clear();
});

4 本地开发特殊适配 #

本地使用HTTP调试时，可临时将Keycloak Realm设置中的Require SSL改为None，同时将客户端Web Origins配置为*，生产环境必须回滚该配置。 #

内容的提问来源于stack exchange，提问作者franfrLor