ASP.NET Core server-side and Blazor Web App additional security scenarios

This article explains how to configure server-side Blazor for additional security scenarios, including how to pass tokens to a Blazor app.

Note

The code examples in this article adopt nullable reference types (NRTs) and .NET compiler null-state static analysis, which are supported in ASP.NET Core in .NET 6 or later. When targeting ASP.NET Core 5.0 or earlier, remove the null type designation (?) from the string?, TodoItem[]?, WeatherForecast[]?, and IEnumerable<GitHubBranch>? types in the article's examples.

Pass tokens to a server-side Blazor app

For Blazor Web Apps, guidance on how to pass tokens to Razor components should be addressed in the documentation (dotnet/AspNetCore.Docs #31691) in 2025 for a preview release of .NET 10.

For more information, see the following issues:

• Access AuthenticationStateProvider in outgoing request middleware (dotnet/aspnetcore #52379): This is the current issue to address passing tokens in Blazor Web Apps, currently scheduled for .NET 10 (late 2025).
• Problem providing Access Token to HttpClient in Interactive Server mode (dotnet/aspnetcore #52390): This issue was closed as a duplicate of the preceding issue, but it contains helpful discussion and potential workaround strategies.

For Blazor Server, view the 7.0 version of this article section.

Set the authentication scheme

For an app that uses more than one Authentication Middleware and thus has more than one authentication scheme, the scheme that Blazor uses can be explicitly set in the endpoint configuration of the Program file. The following example sets the OpenID Connect (OIDC) scheme:

using Microsoft.AspNetCore.Authentication.OpenIdConnect;

...

app.MapRazorComponents<App>().RequireAuthorization(
    new AuthorizeAttribute
    {
        AuthenticationSchemes = OpenIdConnectDefaults.AuthenticationScheme
    })
    .AddInteractiveServerRenderMode();

Circuit handler to capture users for custom services

Use a CircuitHandler to capture a user from the AuthenticationStateProvider and set the user in a service. If you want to update the user, register a callback to AuthenticationStateChanged and enqueue a Task to obtain the new user and update the service. The following example demonstrates the approach.

In the following example:

• OnConnectionUpAsync is called every time the circuit reconnects, setting the user for the lifetime of the connection. Only the OnConnectionUpAsync method is required unless you implement updates via a handler for authentication changes (AuthenticationChanged in the following example).
• OnCircuitOpenedAsync is called to attach the authentication changed handler, AuthenticationChanged, to update the user.
• The catch block of the UpdateAuthentication task takes no action on exceptions because there's no way to report the exceptions at this point in code execution. If an exception is thrown from the task, the exception is reported elsewhere in app.

UserService.cs:

using System.Security.Claims;
using Microsoft.AspNetCore.Components.Authorization;
using Microsoft.AspNetCore.Components.Server.Circuits;

public class UserService
{
    private ClaimsPrincipal currentUser = new(new ClaimsIdentity());

    public ClaimsPrincipal GetUser() => currentUser;

    internal void SetUser(ClaimsPrincipal user)
    {
        if (currentUser != user)
        {
            currentUser = user;
        }
    }
}

internal sealed class UserCircuitHandler(
        AuthenticationStateProvider authenticationStateProvider,
        UserService userService) 
        : CircuitHandler, IDisposable
{
    public override Task OnCircuitOpenedAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        authenticationStateProvider.AuthenticationStateChanged += 
            AuthenticationChanged;

        return base.OnCircuitOpenedAsync(circuit, cancellationToken);
    }

    private void AuthenticationChanged(Task<AuthenticationState> task)
    {
        _ = UpdateAuthentication(task);

        async Task UpdateAuthentication(Task<AuthenticationState> task)
        {
            try
            {
                var state = await task;
                userService.SetUser(state.User);
            }
            catch
            {
            }
        }
    }

    public override async Task OnConnectionUpAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        var state = await authenticationStateProvider.GetAuthenticationStateAsync();
        userService.SetUser(state.User);
    }

    public void Dispose()
    {
        authenticationStateProvider.AuthenticationStateChanged -= 
            AuthenticationChanged;
    }
}

In the Program file:

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.Extensions.DependencyInjection.Extensions;

...

builder.Services.AddScoped<UserService>();
builder.Services.TryAddEnumerable(
    ServiceDescriptor.Scoped<CircuitHandler, UserCircuitHandler>());

Use the service in a component to obtain the user:

@inject UserService UserService

<h1>Hello, @(UserService.GetUser().Identity?.Name ?? "world")!</h1>

To set the user in middleware for MVC, Razor Pages, and in other ASP.NET Core scenarios, call SetUser on the UserService in custom middleware after the Authentication Middleware runs, or set the user with an IClaimsTransformation implementation. The following example adopts the middleware approach.

UserServiceMiddleware.cs:

public class UserServiceMiddleware
{
    private readonly RequestDelegate next;

    public UserServiceMiddleware(RequestDelegate next)
    {
        this.next = next ?? throw new ArgumentNullException(nameof(next));
    }

    public async Task InvokeAsync(HttpContext context, UserService service)
    {
        service.SetUser(context.User);
        await next(context);
    }
}

Immediately before the call to app.MapRazorComponents<App>() in the Program file, call the middleware:

app.UseMiddleware<UserServiceMiddleware>();

Access AuthenticationStateProvider in outgoing request middleware

The AuthenticationStateProvider from a DelegatingHandler for HttpClient created with IHttpClientFactory can be accessed in outgoing request middleware using a circuit activity handler.

Note

For general guidance on defining delegating handlers for HTTP requests by HttpClient instances created using IHttpClientFactory in ASP.NET Core apps, see the following sections of Make HTTP requests using IHttpClientFactory in ASP.NET Core:

• Outgoing request middleware
• Use DI in outgoing request middleware

The following example uses AuthenticationStateProvider to attach a custom user name header for authenticated users to outgoing requests.

First, implement the CircuitServicesAccessor class in the following section of the Blazor dependency injection (DI) article:

Access server-side Blazor services from a different DI scope

Use the CircuitServicesAccessor to access the AuthenticationStateProvider in the DelegatingHandler implementation.

AuthenticationStateHandler.cs:

public class AuthenticationStateHandler(
    CircuitServicesAccessor circuitServicesAccessor) 
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var authStateProvider = circuitServicesAccessor.Services
            .GetRequiredService<AuthenticationStateProvider>();
        var authState = await authStateProvider.GetAuthenticationStateAsync();
        var user = authState.User;

        if (user.Identity is not null && user.Identity.IsAuthenticated)
        {
            request.Headers.Add("X-USER-IDENTITY-NAME", user.Identity.Name);
        }

        return await base.SendAsync(request, cancellationToken);
    }
}

In the Program file, register the AuthenticationStateHandler and add the handler to the IHttpClientFactory that creates HttpClient instances:

builder.Services.AddTransient<AuthenticationStateHandler>();

builder.Services.AddHttpClient("HttpMessageHandler")
    .AddHttpMessageHandler<AuthenticationStateHandler>();