如何在Blazor Server应用的_host.cshtml中实现Keycloak OIDC认证？

一、Keycloak 客户端配置 #

1. 登录Keycloak后台，进入目标Realm，点击「Clients」→「Create」
2. 填写客户端ID（例如BlazorServerApp），保存配置
3. 在客户端详情页设置以下关键参数：
   • Access Type：选择confidential（Blazor Server属于服务器端应用，需此类型）
   • Valid Redirect URIs：添加Blazor应用回调地址，格式如https://localhost:5001/signin-oidc（根据项目实际端口调整）
   • Web Origins：开发环境填*，生产环境填对应应用域名
4. 切换到「Credentials」标签，复制生成的「Secret」值，后续项目配置会用到
5. 记录Keycloak的Realm地址，格式为https://<你的Keycloak域名>/auth/realms/<你的Realm名称>

二、Blazor Server 项目基础配置 #

1. 安装NuGet包：Microsoft.AspNetCore.Authentication.OpenIdConnect
2. 修改appsettings.json，添加OIDC配置节点：

"Authentication": {
  "Oidc": {
    "Authority": "https://<你的Keycloak域名>/auth/realms/<你的Realm名称>",
    "ClientId": "BlazorServerApp",
    "ClientSecret": "<你复制的Keycloak客户端秘钥>",
    "ResponseType": "code",
    "SaveTokens": true,
    "CallbackPath": "/signin-oidc"
  }
}

三、配置认证中间件（Program.cs） #

修改Program.cs，添加认证与授权服务，注意中间件顺序：

var builder = WebApplication.CreateBuilder(args);

// 注册Blazor相关服务
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

// 配置认证方案
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "oidc";
})
.AddCookie("Cookies")
.AddOpenIdConnect("oidc", options =>
{
    builder.Configuration.Bind("Authentication:Oidc", options);
});

// 添加授权服务
builder.Services.AddAuthorization();

var app = builder.Build();

// 环境相关配置
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

// 启用认证和授权（顺序不能错）
app.UseAuthentication();
app.UseAuthorization();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

四、实现强制登录跳转（两种可选方案） #

方案1：通过Razor Pages约定保护 _Host.cshtml #

在Program.cs的AddRazorPages方法中添加授权规则，强制所有访问_Host的请求必须经过认证：

builder.Services.AddRazorPages(options =>
{
    // 保护入口页面，未认证用户自动跳转Keycloak登录
    options.Conventions.AuthorizePage("/_Host");
});

方案2：给 _Host.razor 添加[Authorize]属性 #

直接在_Host.razor文件顶部添加授权属性：

@page "/"
@namespace BlazorServerKeycloak.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@attribute [Authorize]

<!DOCTYPE html>
<html lang="en">
<head>
    <!-- 原有头部内容 -->
</head>
<body>
    <!-- 原有页面内容 -->
</body>
</html>

注意事项 #

• 必须启用HTTPS：OIDC协议要求HTTPS通信，开发环境需在项目属性中开启SSL，确保回调地址为HTTPS格式
• 验证Keycloak端点：可访问{Authority}/.well-known/openid-configuration确认OIDC元数据正常返回
• 测试流程：启动应用后，访问任意页面会自动跳转到Keycloak登录页，登录成功后返回应用

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