ASP.NET Core SignalR 中的身份验证和授权

本文介绍如何使用 SignalR 在 ASP.NET Core 应用程序中对用户进行身份验证和授权。

对连接到 SignalR 中心的用户进行身份验证

SignalR 可与 ASP.NET Core 身份验证配合使用，将用户与每个连接关联。 在中心，可以从 HubConnectionContext.User 属性访问身份验证数据。 身份验证允许中心对与用户关联的所有连接调用方法。 有关详细信息，请参阅在 SignalR 中管理用户和组。 多个连接可以与单个用户相关联。

以下代码是使用 SignalR 和 ASP.NET Core 身份验证的示例：

using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using SignalRAuthenticationSample.Data;
using SignalRAuthenticationSample.Hubs;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();
builder.Services.AddRazorPages();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseMigrationsEndPoint();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();
app.MapHub<ChatHub>("/chat");

app.Run();

Note

如果令牌在连接生存期内过期，默认情况下连接会继续工作。 如果后续请求不发送新的访问令牌，LongPolling 和 ServerSentEvents 连接将失败。 若要在身份验证令牌过期时关闭连接，请设置 CloseOnAuthenticationExpiration 选项。

连接生存期内的用户和角色更改

SignalR 在建立连接时捕获经过身份验证的用户，并在连接的生存期内缓存该用户。 缓存主体通过 Context.User 属性向中心方法公开，HubCallerContext.User用于授权中心方法调用。 SignalR 无论身份验证方案如何，都不会在连接期间自动重新验证用户。 此行为适用于所有方案，包括 cookie 身份验证和持有者令牌身份验证。

对建立连接后发生的用户的标识、角色或声明的更改不会反映在现有连接上。 即使基础传输发出新的 HTTP 请求（例如 LongPolling 和 ServerSentEvents 传输），此行为也适用。 尽管 ASP.NET Core身份验证中间件会重新验证其中每个 HTTP 请求，但SignalR继续使用建立连接时缓存的主体。

请考虑以下情况：

• 应用使用 cookie 身份验证和 LongPolling 传输。 相同的行为适用于持有者令牌身份验证和 ServerSentEvents 传输。
• 用户以 Editor 角色登录，并具有打开的 SignalR 连接。
• 该应用会移除该用户的 Editor 角色。

在下一个长时间轮询请求中，身份验证中间件可能会对没有 Editor 角色的用户进行身份验证。 例如，如果角色是从数据存储中加载的，或者 cookie 被刷新，就可能会发生这种情况。 但是，Hub 仍会授权用户对 [Authorize(Roles = "Editor")] Hub 方法的调用，因为 Context.User（HubCallerContext.User）仍持有在角色被移除之前缓存的主体。 在连接关闭之前，用户可以继续调用仅限 Editor 的 Hub 方法。

若要对活动连接强制实施更新的授权，请采用以下方法之一：

• 关闭受影响的连接，使客户端重新连接并重新进行身份验证。 对于持有者令牌身份验证， CloseOnAuthenticationExpiration 选项在身份验证令牌过期时关闭连接。
• 在中心方法中对当前数据（如用户的当前角色或数据存储中的声明）执行授权检查，而不是仅依赖缓存的主体。

Cookie身份验证

在基于浏览器的应用中，cookie 身份验证允许现有用户凭据自动流向 SignalR 连接。 使用浏览器客户端时，无需额外配置。 如果用户登录到应用，则 SignalR 连接会自动继承此身份验证。

Cookies 是发送访问令牌的特定于浏览器的方法，但非浏览器客户端可以发送它们。 使用 .NET 客户端时，可以在 Cookies 调用中配置 .WithUrl 属性，以提供 cookie。 但是，从 .NET 客户端使用 cookie 身份验证时，应用必须提供 API 来交换 cookie 的身份验证数据。

重要

从 ASP.NET Core 10 开始，启用 cookie 身份验证时，已知的 API 终结点将不再重定向到登录页面。 而是返回 401/403 状态代码。 有关详细信息，请参阅 ASP.NET Core 中的 API 终结点身份验证行为。

Bearer 令牌身份验证

客户端可以提供访问令牌，而不是使用 cookie。 服务器验证令牌并使用它来标识用户。 对于发出多个 HTTP 请求的传输（例如 LongPolling ，和 ServerSentEvents），身份验证在每个请求上运行，但 SignalR 会在连接的生存期内缓存生成的主体。 与 cookie 身份验证一样，SignalR 不会在连接的整个生命周期内自动重新验证用户，以检查令牌是否已被吊销，或用户的角色或声明是否已发生变化。 有关详细信息，请参阅 连接生存期内的用户和角色更改。

在 JavaScript 客户端中，可以使用 accessTokenFactory 选项提供令牌。

// Connect, using the token we got.
this.connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/chat", { accessTokenFactory: () => this.loginToken })
    .build();

在 .NET 客户端中，有一个类似的 AccessTokenProvider 属性可用于配置令牌：

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options =>
    { 
        options.AccessTokenProvider = () => Task.FromResult(_myAccessToken);
    })
    .Build();

Note

访问令牌函数会在由发出的SignalR HTTP 请求之前调用。 如果需要续订令牌才能使连接保持活动状态，请从此函数中执行续订并返回更新的令牌。 令牌可能需要续订，以便在连接期间不会过期。

在标准 Web API 中，持有者令牌在 HTTP 标头中发送。 但是，浏览器不能在 WebSocket 和 Server-Sent 事件 API 上设置自定义标头，例如 Authorization。 由于浏览器的这一限制，当客户端在浏览器中运行时，SignalR 会针对这些传输方式将令牌作为查询字符串参数发送。

查询字符串回退是浏览器 API 的约束，而不是 SignalR 或 WebSocket 协议的限制。 非浏览器客户端（如 .NET 客户端）会在 Authorization 标头中发送令牌。 反向代理（例如位于 backend-for-frontend (BFF) 前面的 YARP）也可以向经代理的 WebSocket 请求添加 Authorization 标头，这样后端便可使用该标头而不是查询字符串进行身份验证。

内置JWT身份验证

在服务器上，持有者令牌身份验证是使用 JSON Web 令牌 （JWT） Bearer 中间件配置的：

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.SignalR;
using Microsoft.EntityFrameworkCore;
using SignalRAuthenticationSample.Data;
using SignalRAuthenticationSample.Hubs;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using SignalRAuthenticationSample;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddAuthentication(options =>
{
    // Identity made Cookie authentication the default.
    // However, we want JWT Bearer Auth to be the default.
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
  {
      // Configure the Authority to the expected value for
      // the authentication provider. This ensures the token
      // is appropriately validated.
      options.Authority = "Authority URL"; // TODO: Update URL

      // We have to hook the OnMessageReceived event in order to
      // allow the JWT authentication handler to read the access
      // token from the query string when a WebSocket or 
      // Server-Sent Events request comes in.

      // Sending the access token in the query string is required when using WebSockets or ServerSentEvents
      // due to a limitation in Browser APIs. We restrict it to only calls to the
      // SignalR hub in this code.
      // See https://docs.microsoft.com/aspnet/core/signalr/security#access-token-logging
      // for more information about security considerations when using
      // the query string to transmit the access token.
      options.Events = new JwtBearerEvents
      {
          OnMessageReceived = context =>
          {
              var accessToken = context.Request.Query["access_token"];

              // If the request is for our hub...
              var path = context.HttpContext.Request.Path;
              if (!string.IsNullOrEmpty(accessToken) &&
                  (path.StartsWithSegments("/hubs/chat")))
              {
                  // Read the token out of the query string
                  context.Token = accessToken;
              }
              return Task.CompletedTask;
          }
      };
  });

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

// Change to use Name as the user identifier for SignalR
// WARNING: This requires that the source of your JWT token 
// ensures that the Name claim is unique!
// If the Name claim isn't unique, users could receive messages 
// intended for a different user!
builder.Services.AddSingleton<IUserIdProvider, NameUserIdProvider>();

// Change to use email as the user identifier for SignalR
// builder.Services.AddSingleton<IUserIdProvider, EmailBasedUserIdProvider>();

// WARNING: use *either* the NameUserIdProvider *or* the 
// EmailBasedUserIdProvider, but do not use both. 

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseMigrationsEndPoint();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();
app.MapHub<ChatHub>("/chatHub");

app.Run();

Note

由于存在浏览器 API 限制，当连接 WebSocket 和服务器发送的事件时，将在浏览器上使用查询字符串。 使用 HTTPS 时，TLS 连接会保护查询字符串值。 但是，许多服务器会记录查询字符串值。 有关详细信息，请参阅 ASP.NET Core SignalR 中的安全注意事项。 SignalR 使用标头在支持它们的环境中传输令牌，例如 .NET 和 Java 客户端。

Identity 服务器 JWT 身份验证

使用 Duende IdentityServer 时，向项目添加 PostConfigureOptions<TOptions> 服务：

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Extensions.Options;
public class ConfigureJwtBearerOptions : IPostConfigureOptions<JwtBearerOptions>
{
    public void PostConfigure(string name, JwtBearerOptions options)
    {
        var originalOnMessageReceived = options.Events.OnMessageReceived;
        options.Events.OnMessageReceived = async context =>
        {
            await originalOnMessageReceived(context);

            if (string.IsNullOrEmpty(context.Token))
            {
                var accessToken = context.Request.Query["access_token"];
                var path = context.HttpContext.Request.Path;

                if (!string.IsNullOrEmpty(accessToken) &&
                    path.StartsWithSegments("/hubs"))
                {
                    context.Token = accessToken;
                }
            }
        };
    }
}

在添加用于身份验证的服务（使用 AddAuthentication 方法）和服务器的身份验证处理程序 Identity （使用 AddIdentityServerJwt 方法）后注册服务：

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Extensions.DependencyInjection.Extensions;
using SignalRAuthenticationSample.Hubs;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
    .AddIdentityServerJwt();
builder.Services.TryAddEnumerable(
    ServiceDescriptor.Singleton<IPostConfigureOptions<JwtBearerOptions>,
        ConfigureJwtBearerOptions>());

builder.Services.AddRazorPages();

var app = builder.Build();

// Code removed for brevity.

Cookies 与持有者令牌

Cookies 是浏览器特有的。 从其他类型的客户端发送它们相比于发送持有者令牌要更加复杂。 除非应用只需从浏览器客户端对用户进行身份验证，否则不建议使用 Cookie 身份验证。 Bearer 使用浏览器客户端以外的客户端时，建议使用令牌身份验证。

Windows 身份验证

如果在应用中配置 了 Windows 身份验证 ， SignalR 则可以使用该标识来保护中心。 但是，若要向单个用户发送消息，需要添加自定义用户 ID 提供程序。 Windows 身份验证系统不提供“名称标识符”声明。 SignalR 使用该声明来确定用户名。

添加一个新类，该类实现 IUserIdProvider 并检索用户中的一个声明以用作标识符。 例如，若要使用“名称”声明（即 [Domain]/[Username] 形式的 Windows 用户名），请创建以下类：

public class NameUserIdProvider : IUserIdProvider
{
    public string GetUserId(HubConnectionContext connection)
    {
        return connection.User?.Identity?.Name;
    }
}

使用 ClaimTypes.Name 中的任何值（例如Windows SID 标识符等），而不是 User。

Note

指定的值在系统中的所有用户中必须是唯一的。 否则，面向一个用户的消息最终可能会到达其他用户。

在 Program.cs 文件中注册此组件：

using Microsoft.AspNetCore.Authentication.Negotiate;
using Microsoft.AspNetCore.SignalR;
using SignalRAuthenticationSample;

var builder = WebApplication.CreateBuilder(args);
var services = builder.Services;

services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
services.AddRazorPages();

services.AddSignalR();
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();

var app = builder.Build();

// Code removed for brevity.

在.NET客户端中，必须通过设置 UseDefaultCredentials 属性来启用Windows 身份验证：

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options =>
    {
        options.UseDefaultCredentials = true;
    })
    .Build();

Microsoft Edge 支持 Windows 身份验证，但并非所有浏览器都支持。 例如，在 Chrome 和 Safari 中，尝试使用 Windows 身份验证和 WebSocket 会失败。 当 Windows 身份验证失败时，客户端会尝试回退到其他传输方式，而这些方式可能会奏效。

使用声明自定义标识处理

进行身份验证的应用可以从用户声明中派生用户 ID SignalR。 若要指定 SignalR 如何创建用户 ID，请实现 IUserIdProvider 并注册该实现。

示例代码演示了如何使用声明来选择用户的电子邮件地址作为标识属性。

Note

指定的值在系统中的所有用户中必须是唯一的。 否则，面向一个用户的消息最终可能会到达其他用户。

public class EmailBasedUserIdProvider : IUserIdProvider
{
    public virtual string GetUserId(HubConnectionContext connection)
    {
        return connection.User?.FindFirst(ClaimTypes.Email)?.Value!;
    }
}

帐户注册将类型为 ClaimsTypes.Email 的声明添加到 ASP.NET 身份数据库中。

public async Task<IActionResult> OnPostAsync(string returnUrl = null)
{
    returnUrl ??= Url.Content("~/");
    ExternalLogins = (await _signInManager.GetExternalAuthenticationSchemesAsync())
                                                                          .ToList();
    if (ModelState.IsValid)
    {
        var user = CreateUser();

        await _userStore.SetUserNameAsync(user, Input.Email, CancellationToken.None);
        await _emailStore.SetEmailAsync(user, Input.Email, CancellationToken.None);
        var result = await _userManager.CreateAsync(user, Input.Password);

        // Add the email claim and value for this user.
        await _userManager.AddClaimAsync(user, new Claim(ClaimTypes.Email, Input.Email));

        // Remaining code removed for brevity.

在 Program.cs 文件中注册此组件：

builder.Services.AddSingleton<IUserIdProvider, EmailBasedUserIdProvider>();

授权用户访问集线器和其方法

默认情况下，未经身份验证的用户可以调用中心中的所有方法。 若要要求进行身份验证，请将 AuthorizeAttribute 特性应用于中心：

[Authorize]
public class ChatHub: Hub
{
}

可使用 [Authorize] 特性的构造函数参数和属性将访问权限仅限于匹配特定授权策略的用户。 例如，使用调用 MyAuthorizationPolicy自定义授权策略时，只有匹配该策略的用户才能使用以下代码访问中心：

[Authorize("MyAuthorizationPolicy")]
public class ChatPolicyHub : Hub
{
    public override async Task OnConnectedAsync()
    {
        await Clients.All.SendAsync("ReceiveSystemMessage", 
                                    $"{Context.UserIdentifier} joined.");
        await base.OnConnectedAsync();
    }
    // Code removed for brevity.

[Authorize] 特性可应用于单个中心方法。 如果当前用户与应用于方法的策略不匹配，则会向调用方返回错误：

[Authorize]
public class ChatHub : Hub
{
    public async Task Send(string message)
    {
        // ... Send a message to all users ...
    }

    [Authorize("Administrators")]
    public void BanUser(string userName)
    {
        // ... Ban a user from the chat room (something only Administrators can do) ...
    }
}

使用授权处理程序自定义集线器方法授权

当中心方法要求授权时，SignalR 会为授权处理程序提供一个自定义资源。 资源是 HubInvocationContext 的一个实例。 HubInvocationContext 包括 HubCallerContext、正在调用的中心方法的名称以及中心方法的参数。

请考虑聊天室的示例，该聊天室允许多个组织通过Microsoft Entra ID登录。 拥有 Microsoft 帐户的任何人都可以登录聊天，但只有所属组织的成员才能阻止用户或查看用户的聊天历史记录。 此外，可能需要限制特定用户的某些功能。 在此场景中，请注意 DomainRestrictedRequirement 如何充当自定义IAuthorizationRequirement。 由于传入了 HubInvocationContext 资源参数，因此内部逻辑可以检查调用 Hub 时的上下文，并决定是否允许用户执行各个 Hub 方法：

[Authorize]
public class ChatHub : Hub
{
    public void SendMessage(string message)
    {
    }

    [Authorize("DomainRestricted")]
    public void BanUser(string username)
    {
    }

    [Authorize("DomainRestricted")]
    public void ViewUserHistory(string username)
    {
    }
}

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.SignalR;

namespace SignalRAuthenticationSample;

public class DomainRestrictedRequirement :
    AuthorizationHandler<DomainRestrictedRequirement, HubInvocationContext>,
    IAuthorizationRequirement
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
        DomainRestrictedRequirement requirement,
        HubInvocationContext resource)
    {
        if (context.User.Identity != null &&
          !string.IsNullOrEmpty(context.User.Identity.Name) && 
          IsUserAllowedToDoThis(resource.HubMethodName,
                               context.User.Identity.Name) &&
          context.User.Identity.Name.EndsWith("@microsoft.com"))
        {
                context.Succeed(requirement);
            
        }
        return Task.CompletedTask;
    }

    private bool IsUserAllowedToDoThis(string hubMethodName,
        string currentUsername)
    {
        return !(currentUsername.Equals("asdf42@microsoft.com") &&
            hubMethodName.Equals("banUser", StringComparison.OrdinalIgnoreCase));
    }
}

在 Program.cs 文件中，添加新策略，提供自定义 DomainRestrictedRequirement 要求作为参数来创建 DomainRestricted 策略：

using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using SignalRAuthenticationSample;
using SignalRAuthenticationSample.Data;
using SignalRAuthenticationSample.Hubs;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
var services = builder.Services;

services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
services.AddDatabaseDeveloperPageExceptionFilter();

services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

services.AddAuthorization(options =>
   {
       options.AddPolicy("DomainRestricted", policy =>
       {
           policy.Requirements.Add(new DomainRestrictedRequirement());
       });
   });

services.AddRazorPages();

var app = builder.Build();

// Code removed for brevity.

在前面的示例中，DomainRestrictedRequirement 类既是 IAuthorizationRequirement，也是该要求的 AuthorizationHandler。 可以将这两个组件拆分为不同的类，以分离关注事项。 此示例中的方法提供了无需在启动期间注入 AuthorizationHandler 的好处，因为要求和处理程序是相同的。

其他资源

• BearerASP.NET Core中的令牌身份验证（博客）
• 基于资源的授权
• 查看或下载示例代码（如何下载）