.NET 9应用中如何为Scalar全局配置JWT Token支持？

问题描述 #

我正在.NET 9应用中启用Scalar，需要为其全局配置JWT Token支持，就像Swagger支持全局添加JWT Token认证那样。但我找不到相关的文档或示例说明如何在Scalar中实现这一点。请问是否可以为Scalar设置全局JWT Token支持？如果可以，该如何实现？

解决方案 #

要实现Scalar的全局JWT Token支持，需分两步完成：先在OpenAPI文档中定义Bearer认证方案，再在Scalar配置中绑定该方案并设置全局Token。

1. 配置OpenAPI的Bearer认证方案 #

在services.AddOpenApi()中添加SecurityScheme，确保OpenAPI文档包含JWT认证的元信息，Scalar依赖该信息识别认证方式：

services.AddOpenApi(options =>
{
    // 注册Bearer认证方案
    options.AddSecurity("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "请输入JWT Token，格式为Bearer {Token}"
    });

    // 可选：全局应用认证要求，让所有接口默认需要JWT认证
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

2. 配置Scalar的全局JWT支持 #

在app.MapScalarApiReference()中指定首选认证方案，并设置全局Token，让所有请求自动带上该Token：

app.MapOpenApi();
app.MapScalarApiReference(options =>
{
    options.WithTheme(ScalarTheme.Moon)
        .WithDarkMode(true)
        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
        .WithDarkModeToggle(false)
        // 指定默认使用Bearer认证方案
        .WithPreferredScheme("Bearer")
        // 设置全局JWT Token，自动添加到所有请求的Authorization头
        .WithHttpBearerAuthentication(bearer =>
        {
            bearer.Token = "your-actual-jwt-token";
            // 可选：自定义Token前缀，默认值为"Bearer"
            // bearer.Prefix = "Bearer";
        });

    // 确保Scalar界面默认选中Bearer认证选项
    options.Authentication = new ScalarAuthenticationOptions
    {
        PreferredSecurityScheme = "Bearer"
    };
});

关键配置说明 #

• AddSecurity("Bearer", ...)：在OpenAPI元数据中注册Bearer认证方案，是Scalar识别认证方式的前提。
• WithPreferredScheme("Bearer")：告知Scalar默认使用Bearer认证方案发起请求。
• WithHttpBearerAuthentication：设置全局JWT Token，Scalar会自动将该Token注入所有请求的Authorization请求头。
• Authentication.PreferredSecurityScheme：确保Scalar界面默认选中Bearer选项，无需手动切换认证方式。

使用的包 #

• Scalar.AspNetCore (1.2.49)
• Microsoft.AspNetCore.OpenApi (9.0.0)

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