如何在Blazor应用中配置Gitlab作为外部登录身份验证服务

这个需求完全可以实现，ASP.NET Core 内置了完善的 OAuth2.0 身份验证支持，对接自建 Gitlab 实例只需要简单的配置即可完成，不需要额外的第三方依赖，下面是完整的实现步骤：

首先需要在你的团队私有 Gitlab 实例上生成对接用的凭证：

• 登录你的 Gitlab 账号，进入偏好设置→应用页面
• 填写应用名称，重定向 URI 填写你的 Blazor Server 应用访问地址加后缀 /signin-gitlab，示例：https://你团队Blazor应用域名/signin-gitlab，这个路径是 ASP.NET OAuth 中间件默认的回调路径，不要随意修改
• 权限范围按需勾选，仅实现登录功能只需要勾选read_user即可，如果后续需要调用 Gitlab 接口操作仓库等，可以额外勾选api等权限
• 创建应用后保存生成的 Application ID 和 Secret，这两个值是后续 Blazor 端配置需要用到的核心凭证

2.1 安装依赖包 #

如果你的项目没有预装 OAuth 相关组件，先安装官方 NuGet 包：
Microsoft.AspNetCore.Authentication.OAuth

2.2 修改 Program.cs 配置 #

在项目启动文件中添加 Gitlab 身份验证配置，注意中间件顺序不要出错：

using System.Net.Http.Headers;
using System.Security.Claims;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);

// 添加身份验证服务
builder.Services.AddAuthentication(options =>
    {
        // 如果不需要完整的Identity体系，用Cookie作为默认登录方案即可
        options.DefaultScheme = "Cookies";
        options.DefaultChallengeScheme = "GitLab";
    })
    .AddCookie("Cookies")
    .AddOAuth("GitLab", options =>
    {
        // 替换为你团队自建Gitlab的域名，不要加末尾斜杠
        options.AuthorizationEndpoint = "https://你团队Gitlab域名/oauth/authorize";
        options.TokenEndpoint = "https://你团队Gitlab域名/oauth/token";
        options.UserInformationEndpoint = "https://你团队Gitlab域名/api/v4/user";

        // 从配置文件读取Gitlab凭证，不要硬编码
        options.ClientId = builder.Configuration["GitLab:ClientId"];
        options.ClientSecret = builder.Configuration["GitLab:ClientSecret"];

        options.Scope.Add("read_user");
        options.CallbackPath = "/signin-gitlab";

        // 映射Gitlab返回的用户信息到ASP.NET身份声明
        options.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id");
        options.ClaimActions.MapJsonKey(ClaimTypes.Name, "username");
        options.ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
        options.ClaimActions.MapJsonKey("avatar_url", "avatar_url");

        options.Events = new OAuthEvents
        {
            OnCreatingTicket = async context =>
            {
                // 拉取Gitlab用户信息
                using var request = new HttpRequestMessage(HttpMethod.Get, context.Options.UserInformationEndpoint);
                request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
                request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", context.AccessToken);

                using var response = await context.Backchannel.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, context.CancellationToken);
                response.EnsureSuccessStatusCode();

                var userRoot = JsonDocument.Parse(await response.Content.ReadAsStringAsync()).RootElement;
                context.RunClaimActions(userRoot);
            }
        };
    });

// 保留你原有项目的服务配置
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

var app = builder.Build();

// 中间件顺序不要调整，必须先启用Authentication再启用Authorization
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();

2.3 配置凭证信息 #

在 appsettings.json 中添加 Gitlab 凭证配置，避免硬编码泄露敏感信息：

{
  "GitLab": {
    "ClientId": "你在Gitlab生成的Application ID",
    "ClientSecret": "你在Gitlab生成的Secret"
  }
}

• 如果你用的是默认 ASP.NET Identity UI，配置完成后登录页会自动显示 Gitlab 登录选项
• 如果是自定义登录页，只需要添加一个触发 Gitlab 验证的入口，直接跳转 /signin-gitlab 或者调用 HttpContext.ChallengeAsync("GitLab") 即可

注意事项：

1. Gitlab 中填写的回调地址必须和 Blazor 端实际访问地址完全一致，包括 http/https 协议、域名、端口，否则会报回调地址不匹配错误
2. 开发环境如果自建 Gitlab 用的是自签名证书，可以临时配置 HttpClient 跳过证书校验，生产环境必须替换为可信证书避免安全风险
3. 生成的 Gitlab Secret 不要提交到代码仓库，生产环境建议用密钥管理器或者环境变量存储

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