Blazor Authentication and Authorization: A Complete Guide

In modern web applications, controlling access to features and data is critical. Blazor, Microsoft's framework for building interactive web UIs with C#, offers robust authentication and authorization mechanisms. Whether you're building a Blazor Server app where UI logic runs on the server, or a Blazor WebAssembly app that runs entirely in the browser, you need to ensure that only authenticated users can access protected resources and that they have the right permissions. This tutorial covers both hosting models, from integrating ASP.NET Core Identity to using JWT tokens and custom policies. You'll learn how to secure your Blazor components, handle authentication state, and avoid common pitfalls. By the end, you'll be able to implement a complete authentication and authorization system that is both secure and maintainable.

Understanding Authentication and Authorization in Blazor

Authentication is the process of verifying who a user is, while authorization determines what an authenticated user is allowed to do. In Blazor, these concepts are implemented using ASP.NET Core's built-in authentication middleware and the AuthorizeView component. Blazor Server uses a persistent SignalR connection, so authentication state is managed on the server. Blazor WebAssembly runs entirely in the browser, so authentication relies on tokens (typically JWT) stored in the browser. Both models support cookie-based authentication and external providers like Google or Microsoft. Understanding the hosting model is crucial because it affects how you manage authentication state and protect resources.

// Blazor Server - Configure Services
services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.LoginPath = "/login";
        options.AccessDeniedPath = "/access-denied";
    });
services.AddAuthorization();

Setting Up ASP.NET Core Identity with Blazor

ASP.NET Core Identity provides a complete user management system including registration, login, password reset, and role management. To integrate with Blazor, you need to scaffold Identity and then create Blazor components that interact with it. For Blazor Server, you can use the built-in Identity UI or create custom pages. For Blazor WebAssembly, you typically use a separate API project that handles authentication and issues JWT tokens. Below is an example of configuring Identity in a Blazor Server app.

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<ApplicationDbContext>();
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();

Using AuthorizeView and the [Authorize] Attribute

Blazor provides two primary ways to control access: the AuthorizeView component and the [Authorize] attribute. AuthorizeView is used in Razor markup to conditionally render content based on the user's authentication status and roles. The [Authorize] attribute can be applied to pages (components with @page) to restrict access entirely. You can also specify roles or policies. Here's an example of both.

@page "/admin"
@attribute [Authorize(Roles = "Admin")]

<h3>Admin Panel</h3>
<p>Welcome, @context.User.Identity.Name!</p>

<AuthorizeView Roles="Admin">
    <Authorized>
        <button @onclick="DeleteAllUsers">Delete All Users</button>
    </Authorized>
    <NotAuthorized>
        <p>You do not have permission to delete users.</p>
    </NotAuthorized>
</AuthorizeView>

@code {
    private void DeleteAllUsers() { /* ... */ }
}

Implementing Custom Authorization Policies

Sometimes role-based authorization is not enough. You may need to check specific claims or complex conditions. ASP.NET Core allows you to define custom policies using the AuthorizationHandler. For example, you might want to allow only users who are both in the 'Admin' role and have a 'Department' claim of 'IT'. Here's how to implement a custom policy.

public class DepartmentRequirement : IAuthorizationRequirement
{
    public string Department { get; }
    public DepartmentRequirement(string department) => Department = department;
}

public class DepartmentAuthorizationHandler : AuthorizationHandler<DepartmentRequirement>
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, DepartmentRequirement requirement)
    {
        if (context.User.IsInRole("Admin") &&
            context.User.HasClaim(c => c.Type == "Department" && c.Value == requirement.Department))
        {
            context.Succeed(requirement);
        }
        return Task.CompletedTask;
    }
}

// Register in Program.cs
builder.Services.AddSingleton<IAuthorizationHandler, DepartmentAuthorizationHandler>();
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ITAdmin", policy =>
        policy.Requirements.Add(new DepartmentRequirement("IT")));
});

Blazor WebAssembly JWT Authentication

In Blazor WebAssembly, authentication is typically done via JWT tokens. The client app sends a login request to a server API, receives a token, and then includes that token in subsequent requests. The token is stored in the browser's localStorage or sessionStorage. Blazor provides the AuthenticationStateProvider to manage the authentication state. Here's a simplified example of a custom AuthenticationStateProvider for JWT.

public class JwtAuthenticationStateProvider : AuthenticationStateProvider
{
    private readonly HttpClient _httpClient;
    private readonly ILocalStorageService _localStorage;

    public JwtAuthenticationStateProvider(HttpClient httpClient, ILocalStorageService localStorage)
    {
        _httpClient = httpClient;
        _localStorage = localStorage;
    }

    public override async Task<AuthenticationState> GetAuthenticationStateAsync()
    {
        var token = await _localStorage.GetItemAsync<string>("authToken");
        if (string.IsNullOrWhiteSpace(token))
            return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));

        var claims = ParseClaimsFromJwt(token);
        var identity = new ClaimsIdentity(claims, "jwt");
        var user = new ClaimsPrincipal(identity);
        return new AuthenticationState(user);
    }

    public void NotifyUserAuthentication(string token)
    {
        var claims = ParseClaimsFromJwt(token);
        var identity = new ClaimsIdentity(claims, "jwt");
        var user = new ClaimsPrincipal(identity);
        NotifyAuthenticationStateChanged(Task.FromResult(new AuthenticationState(user)));
    }

    public void NotifyUserLogout()
    {
        NotifyAuthenticationStateChanged(Task.FromResult(new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()))));
    }

    private IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
    {
        // Implement JWT parsing logic
    }
}

Protecting API Endpoints and Server-Side Validation

No matter how well you protect the Blazor UI, you must always validate authorization on the server. API endpoints should be protected with the [Authorize] attribute and appropriate policies. In Blazor Server, the server-side code is already protected, but in WebAssembly, the client-side checks are merely cosmetic. Always assume that a malicious user can bypass client-side checks. Here's an example of a protected API endpoint.

[ApiController]
[Route("api/[controller]")]
[Authorize(Policy = "ITAdmin")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Only IT Admins can access this
        return new List<WeatherForecast>();
    }
}

Handling Authentication State Changes and Logout

When a user logs out, you need to clear the authentication state and redirect appropriately. In Blazor Server, you can use the SignOutAsync method from the HttpContext. In Blazor WebAssembly, you need to clear the token from storage and notify the AuthenticationStateProvider. Here's an example of logout in Blazor WebAssembly.

@inject IJwtAuthenticationStateProvider AuthStateProvider
@inject NavigationManager Navigation

<button @onclick="Logout">Logout</button>

@code {
    private async Task Logout()
    {
        await _localStorage.RemoveItemAsync("authToken");
        AuthStateProvider.NotifyUserLogout();
        Navigation.NavigateTo("/");
    }
}