[Blazor] Improve AuthenticationStateProvider for SSR with JS-dependent secure storage

[reyou]

Background and Motivation

In Blazor SSR applications, developers often store authentication tokens in browser-based secure storage (e.g., localStorage or sessionStorage). To retrieve these tokens, we rely on JS interop. However, AuthenticationStateProvider is invoked twice, once during server-side rendering and again after client-side hydration.

During the initial server render, JS runtime is unavailable, and any attempt to access secure storage via JS interop results in an exception. Developers must manually catch and suppress this exception, which introduces unnecessary complexity and performance overhead.

Proposed API

Option 1: Event Hooks in AuthenticationStateProvider

Introduce two virtual methods or events to distinguish invocation context:

protected virtual Task OnServerAuthInvokedAsync();
protected virtual Task OnClientAuthInvokedAsync();

These hooks would allow developers to conditionally execute logic based on rendering phase, avoiding JS interop during server render.

Option 2: Environment Flags (less desirable but helpful)

Add runtime flags to detect JS availability:

public static class Environment
{
    public static bool SupportsJsRuntime { get; }
    public static bool JsRuntimeAvailable { get; }
}

These flags would allow developers to safely check for JS interop support before accessing secure storage.

Usage Examples

public class CustomAuthProvider : AuthenticationStateProvider
{
    public override async Task<AuthenticationState> GetAuthenticationStateAsync()
    {
        if (Environment.SupportsJsRuntime && Environment.JsRuntimeAvailable)
        {
            // Safe to access secure storage
        }
        else
        {
            // Fallback logic for server-side render
        }
    }

    protected override Task OnServerAuthInvokedAsync()
    {
        // Skip JS interop
    }

    protected override Task OnClientAuthInvokedAsync()
    {
        // Access secure storage
    }
}

Alternative Designs

• Using IJSRuntime.IsAvailable or similar runtime checks, but this is not currently exposed.

• Wrapping JS interop in try-catch blocks, which is error-prone and inefficient.

Risks

• Minimal risk if implemented as optional hooks or flags.

• Could introduce subtle behavior changes if not clearly documented.

[javiercn]

@reyou thanks for contacting us.

This is not the recommended approach to handle this scenario. Our recommendation is that you use a different implementation for running during prerendering that you prepopulate with the tokens in the auth handler and that you transfer the tokens to the browser via persistent component state.

This is a rough sketch of the solution

1. Define a Token‐Holder Service

Create a scoped service whose token properties carry the [PersistentState] marker. This tells Blazor to capture and serialize these values during prerendering, then restore them when the app becomes interactive.

using Microsoft.AspNetCore.Components.Prerendering;

public class AuthTokenService
{
    [PersistentState]
    public string? AccessToken { get; set; }

    [PersistentState]
    public string? IdToken { get; set; }

    [PersistentState]
    public string? RefreshToken { get; set; }
}

2. Register the Service and OIDC Handler

In Program.cs, add your AuthTokenService as scoped. Configure OpenID Connect and sink the tokens into your service via the built‐in events.

var builder = WebApplication.CreateBuilder(args);

// 1. Register the token service
builder.Services.AddScoped<AuthTokenService>();

// 2. Configure OIDC
builder.Services
    .AddAuthentication(options => {
        options.DefaultScheme = "Cookies";
        options.DefaultChallengeScheme = "oidc";
    })
    .AddCookie("Cookies")
    .AddOpenIdConnect("oidc", options => {
        options.Authority = builder.Configuration["Oidc:Authority"];
        options.ClientId  = builder.Configuration["Oidc:ClientId"];
        options.ClientSecret = builder.Configuration["Oidc:ClientSecret"];
        options.ResponseType   = "code";

        options.SaveTokens = false; // we handle tokens ourselves

        options.Events = new OpenIdConnectEvents
        {
            OnTokenResponseReceived = context =>
            {
                var tokenService = context.HttpContext
                    .RequestServices
                    .GetRequiredService<AuthTokenService>();

                tokenService.AccessToken  = context.TokenEndpointResponse.AccessToken;
                tokenService.IdToken      = context.ProtocolMessage.IdToken;
                tokenService.RefreshToken = context.TokenEndpointResponse.RefreshToken;

                return Task.CompletedTask;
            }
        };
    });

3. Wire Up Persistence in Your Host

Still in Program.cs, map your Blazor root component and register AuthTokenService for persistent capture during prerendering. When the WebAssembly client boots, those same tokens will be rehydrated into the service.

var app = builder.Build();

app.MapRazorComponents<App>()  
   .AddInteractiveServerRenderMode()
   .RegisterPersistentService<AuthTokenService>(ComponentRenderModes.ServerPrerendered);

app.UseStaticFiles();
app.UseRouting();
app.MapFallbackToFile("index.html");

app.Run();

4. Consume the Tokens in WASM Components

Anywhere in your Blazor components—server‐side or WASM—inject AuthTokenService. If prerendering ran, its properties are already populated:

@inject AuthTokenService Tokens

<button @onclick="CallApi">Call Secure API</button>

@code {
    private async Task CallApi()
    {
        var request = new HttpRequestMessage(HttpMethod.Get, "https://api.example.com/data");
        request.Headers.Authorization = new("Bearer", Tokens.AccessToken);
        var response = await Http.SendAsync(request);
        // …
    }
}

[dotnet-policy-service]

This issue has been resolved and has not had any activity for 1 day. It will be closed for housekeeping purposes.

See our Issue Management Policies for more information.

[reyou]

@javiercn Thanks for the detailed response and the suggestion to use a persistent state service for tokens. I understand how that works when tokens are available during prerender (e.g., via OIDC middleware events), but I’m struggling to see how it applies to my scenario.

In my app, I rely on <AuthorizeView> to toggle UI like this:

<AuthorizeView>
    <Authorized>
        <a class="btn btn-sm btn-neutral" href="/account/logout">Logout</a>
    </Authorized>
    <NotAuthorized>
        <a class="btn btn-sm btn-neutral" href="/account/login">Login</a>
    </NotAuthorized>
</AuthorizeView>

That means I need to use AuthenticationStateProvider, which calls GetAuthenticationStateAsync. The problem is:

• On first access, during SSR, I don’t yet have tokens available on the server.
• The tokens only exist in the browser (username/password flow → API → token stored in browser storage).
• So during SSR, GetAuthenticationStateAsync can’t access them.
• If I try to use JS interop to fetch them, it throws because JS isn’t available yet.

In this case, I don’t see how the persistent state approach helps, since there’s nothing to persist from the server side. The result is that <AuthorizeView> always renders NotAuthorized on first load, then flips after hydration once the client can fetch tokens.

My question is: how does your suggested approach help with this scenario where tokens are only available client‑side? Do you expect developers to always accept the “flash of unauthenticated content” during SSR, or is there a recommended pattern for bridging this gap while still using AuthenticationStateProvider?

Another Note:
In my case, I use a username/password authentication flow. When a user logs in for the first time, I cache the token in memory using the AuthenticationService. During the initial load (on browser refresh), I suppress the ProtectedLocalStorage not available error since it occurs during SSR. Once the client-side rendering completes, I hydrate and cache the token. I then reuse the cached authToken while navigating around the app, and there’s no need to suppress errors after that point.

 public async Task<string?> GetAsync(string key)
 {
     try
     {
         ProtectedBrowserStorageResult<string> result = await protectedLocalStorage.GetAsync<string>(key);
         return result.Success ? result.Value : null;
     }
     catch (InvalidOperationException ex) when (ex.Message.Contains(JsInteropUnavailableMessage, StringComparison.OrdinalIgnoreCase))
     {
         // Prerender phase: JS interop not available yet. Return null and continue.
         logger.LogDebug(ex, "ProtectedLocalStorage not available during prerender for GetAsync({Key}). Returning null.", key);
         return null;
     }
     catch (Exception ex)
     {
         logger.LogError(ex, "Unexpected error reading ProtectedLocalStorage key {Key} in GetAsync.", key);
         return null;
     }
 }

[reyou]

@javiercn any comments here? Just curious if this requirement is closed prematurely.