Hub Authentication — JWT Bearer and User-Specific Channels

Securing SignalR Hubs requires special configuration because WebSocket connections cannot send custom HTTP headers like a normal HTTP request. Instead, the JWT token is passed as a query string parameter on the WebSocket upgrade URL, and ASP.NET Core’s JWT Bearer middleware is configured to read it from there. Once authenticated, the Hub has access to Context.User with the full claims from the JWT — enabling user-specific groups, targeted notifications, and role-based Hub method access.

JWT Authentication for SignalR #

// ── Configure JWT Bearer to read token from query string for SignalR ──────
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey         = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(jwtSettings["SecretKey"]!)),
            ValidateIssuer   = true, ValidIssuer   = jwtSettings["Issuer"],
            ValidateAudience = true, ValidAudience = jwtSettings["Audience"],
            ValidateLifetime = true, ClockSkew     = TimeSpan.Zero,
        };

        // ── SignalR-specific: read token from query string ────────────────
        // WebSockets cannot set Authorization header — token must be in URL
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = context =>
            {
                var accessToken = context.Request.Query["access_token"];
                var path        = context.HttpContext.Request.Path;

                // Only read from query string for Hub endpoints
                if (!string.IsNullOrEmpty(accessToken) &&
                    path.StartsWithSegments("/hubs"))
                {
                    context.Token = accessToken;
                }
                return Task.CompletedTask;
            }
        };
    });

// ── Protected Hub ─────────────────────────────────────────────────────────
[Authorize]   // requires valid JWT for the entire hub
public class UserNotificationHub : Hub
{
    public override async Task OnConnectedAsync()
    {
        var userId = Context.User!.FindFirstValue(ClaimTypes.NameIdentifier)!;

        // Add to user-specific group on connect
        await Groups.AddToGroupAsync(Context.ConnectionId, $"user-{userId}");

        // Add to role-based groups
        if (Context.User.IsInRole("Admin"))
            await Groups.AddToGroupAsync(Context.ConnectionId, "admins");

        await base.OnConnectedAsync();
    }

    public override async Task OnDisconnectedAsync(Exception? exception)
    {
        var userId = Context.User?.FindFirstValue(ClaimTypes.NameIdentifier);
        if (userId is not null)
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"user-{userId}");
        await base.OnDisconnectedAsync(exception);
    }

    // ── Admin-only Hub method ─────────────────────────────────────────────
    [Authorize(Roles = "Admin")]
    public async Task BroadcastSystemAlert(string message)
        => await Clients.All.SendAsync("SystemAlert", message);
}

// ── Send to specific user from a service ──────────────────────────────────
public async Task NotifyUserAsync(string userId, string message, CancellationToken ct)
{
    // Clients.User() sends to ALL connections for this user (multiple tabs/devices)
    await _hubContext.Clients.User(userId).SendAsync("Notification", new
    {
        Message   = message,
        Timestamp = DateTime.UtcNow,
    }, ct);
}

Common Mistakes #

Mistake 1 — Not configuring OnMessageReceived to read token from query string (401 on WebSocket) #

❌ Wrong — JWT Bearer only checks Authorization header; WebSocket connections cannot set headers; all connections return 401.

✅ Correct — configure OnMessageReceived to read from context.Request.Query["access_token"] for hub paths.

Mistake 2 — Not re-adding users to groups on reconnection (missing notifications after reconnect) #

❌ Wrong — groups are in-memory; after disconnect/reconnect the user is no longer in any group.

✅ Correct — always re-add to required groups in OnConnectedAsync using claims from the JWT.