Indiko.Hosting.BlazorServer 2.7.1

Indiko.Hosting.BlazorServer

A complete Blazor Server hosting solution with built-in OpenID Connect authentication, PKCE support, security headers, and seamless Indiko Blocks integration.

Features

• Server-side Blazor — full SignalR hub wiring with optional authorization
• OpenID Connect + PKCE — authorization code flow with PKCE, token saving, and claim mapping from the UserInfo endpoint
• Cookie authentication — secure session management backed by OpenID Connect tokens
• Security headers — CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy, CORP, COOP, COEP via NetEscapades.AspNetCore.SecurityHeaders
• Forwarded headers — transparent reverse-proxy support
• HTTPS redirection and HSTS — configurable per environment
• Global authorization — optional AuthorizeFilter applied to all Razor Pages when auth is enabled
• Controllers with Views — optional MVC controller support alongside Blazor
• Development CORS — permissive policy in Development, no automatic CORS in Production
• Indiko Blocks — blocks participating in ConfigureServices, Configure, ConfigureBuilder, and PreRunAsync lifecycle hooks
• Flexible host builder — ConfigureHostBuilder(...) fluent API for Windows Service, containerization, and custom configurations
• Options-driven or property-override configuration — choose the approach that fits your project

Installation

dotnet add package Indiko.Hosting.BlazorServer

Quick Start

1. Create your Startup class

using Indiko.Hosting.BlazorServer;

public class Startup : BlazorServerStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    // Optional: register additional services
    public override void ConfigureServices(IServiceCollection services)
    {
        base.ConfigureServices(services);
        services.AddScoped<IWeatherService, WeatherService>();
    }
}

2. Wire up Program.cs

// Program.cs
return await new BlazorServerHostBootstrapper()
    .RunAsync<Startup>(args);

3. Configure appsettings.json

{
  "ServiceName": "MyBlazorApp",
  "BlazorServerStartupOptions": {
    "AddControllersWithViews": false,
    "EnableForwardedHeaderOptions": true,
    "ForceHttps": false,
    "AddSecurityHeaderSupport": true,
    "AddOpenIdConfiguration": true,
    "AddAuthentication": true
  },
  "OpenIDConnectSettings": {
    "Authority": "https://identity.example.com",
    "ClientId": "blazor-client",
    "ClientSecret": "secret",
    "CallbackPath": "/signin-oidc"
  }
}

4. Add the _Host page

Blazor Server requires a Pages/_Host.cshtml Razor Page as the application shell. The bootstrapper maps it automatically via MapFallbackToPage("/_Host").

Configuration Approaches

There are two ways to configure startup options. Both work identically at runtime — choose whichever suits your project.

Approach A: appsettings.json (recommended)

Add a BlazorServerStartupOptions section to appsettings.json. No code changes needed to toggle features between environments.

{
  "BlazorServerStartupOptions": {
    "AddControllersWithViews": false,
    "EnableForwardedHeaderOptions": true,
    "ForceHttps": false,
    "AddSecurityHeaderSupport": true,
    "AddOpenIdConfiguration": true,
    "AddAuthentication": true
  }
}

All properties default to false when the section is absent or a key is omitted.

Approach B: Property overrides in code

Override the protected virtual properties in your Startup subclass. This approach is useful when options are determined by logic rather than configuration, or when you want compile-time guarantees.

public class Startup : BlazorServerStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    protected override bool AddControllersWithViews      => false;
    protected override bool EnableForwardedHeaderOptions => true;
    protected override bool ForceHttps                  => false;
    protected override bool AddSecurityHeaderSupport     => true;
    protected override bool AddOpenIdConfiguration       => true;
    protected override bool AddAuthentication            => true;
}

Precedence: Property overrides in your subclass always win. The base implementation of each property reads from BlazorServerStartupOptions, so if you do not override a property, the appsettings.json value applies.

Startup Options Reference

EnableForwardedHeaderOptions and ForceHttps are inherited from HostStartupOptions (defined in Indiko.Hosting.Abstractions).

Flexible Host Builder

Because BlazorServerHostBootstrapper is sealed, the fluent ConfigureHostBuilder method is the extension point for host-level configuration:

// Windows Service
return await new BlazorServerHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseWindowsService())
    .RunAsync<Startup>(args);

// Systemd (Linux)
return await new BlazorServerHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseSystemd())
    .RunAsync<Startup>(args);

// Custom Kestrel configuration
return await new BlazorServerHostBootstrapper()
    .ConfigureHostBuilder(b => b.ConfigureWebHostDefaults(web =>
        web.ConfigureKestrel(k => k.ListenAnyIP(8080))))
    .RunAsync<Startup>(args);

// Chain multiple calls
return await new BlazorServerHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseWindowsService())
    .ConfigureHostBuilder(b => b.ConfigureLogging(l => l.AddConsole()))
    .RunAsync<Startup>(args);

Host builder actions are applied after all Indiko Block ConfigureBuilder calls, in the order they are registered.

OpenID Connect Setup

Authentication requires both AddAuthentication and AddOpenIdConfiguration to be true.

appsettings.json

{
  "OpenIDConnectSettings": {
    "Authority": "https://identity.example.com",
    "ClientId": "blazor-client",
    "ClientSecret": "secret",
    "CallbackPath": "/signin-oidc"
  }
}

What the bootstrapper configures automatically

• DefaultScheme: Cookie
• DefaultChallengeScheme: OpenIdConnect
• ResponseType: code (authorization code flow)
• UsePkce: true
• SaveTokens: true
• GetClaimsFromUserInfoEndpoint: true
• NameClaimType: "name" (avoids the WS-Fed claim URI mapping)
• JsonWebTokenHandler.DefaultInboundClaimTypeMap is cleared so claim names match the IdP's JSON names

Accessing tokens from Blazor components

@inject IHttpContextAccessor HttpContextAccessor

@code {
    private async Task<string> GetAccessToken()
    {
        return await HttpContextAccessor.HttpContext
            .GetTokenAsync("access_token");
    }

    private async Task<string> GetIdToken()
    {
        return await HttpContextAccessor.HttpContext
            .GetTokenAsync("id_token");
    }
}

Note: IHttpContextAccessor is registered automatically by the bootstrapper.

Reading user claims

@inject AuthenticationStateProvider AuthStateProvider

@code {
    private string _userName;

    protected override async Task OnInitializedAsync()
    {
        var state = await AuthStateProvider.GetAuthenticationStateAsync();
        _userName = state.User.FindFirst("name")?.Value;
    }
}

Security Headers

Enable via AddSecurityHeaderSupport = true. The OpenIDConnectSettings.Authority value must be configured — it is used to build the form-action CSP directive so the browser can submit to the identity provider.

What is applied

Content Security Policy

object-src 'none';
block-all-mixed-content;
img-src 'self' data:;
form-action 'self' https://identity.example.com;
font-src 'self';
base-uri 'self';
frame-ancestors 'none';
style-src 'unsafe-inline' 'self';
script-src 'nonce-{random}' 'unsafe-inline';

Scripts use a per-request nonce. 'unsafe-inline' is retained as a fallback for browsers that do not support nonces.

Tag helper for nonces

Use the NetEscapades.AspNetCore.SecurityHeaders.TagHelpers package in _Host.cshtml:

<script add-nonce="true" src="/_framework/blazor.server.js"></script>

Development vs Production

In Development the Strict-Transport-Security header is omitted. All other headers are applied in both environments.

Authorization

Global authorization (automatic when auth is enabled)

All Razor Pages require an authenticated user:

// Applied automatically by the bootstrapper:
services.AddRazorPages().AddMvcOptions(options =>
{
    var policy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
    options.Filters.Add(new AuthorizeFilter(policy));
});

The Blazor hub also requires authorization:

endpoints.MapBlazorHub().RequireAuthorization();

Per-component authorization

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

<h1>Admin Dashboard</h1>

AuthorizeView in templates

<AuthorizeView>
    <Authorized>
        <p>Welcome, @context.User.Identity.Name!</p>
    </Authorized>
    <NotAuthorized>
        <p><a href="/login">Please sign in</a></p>
    </NotAuthorized>
</AuthorizeView>

Custom authorization policies

public override void ConfigureServices(IServiceCollection services)
{
    base.ConfigureServices(services);

    services.AddAuthorization(options =>
    {
        options.AddPolicy("AdminOnly", policy =>
            policy.RequireClaim("role", "admin"));

        options.AddPolicy("TenantAccess", policy =>
            policy.RequireClaim("tenant_id"));
    });
}

Razor Pages and MVC Controllers alongside Blazor

Razor Pages

Razor Pages are always registered. They serve as the application shell (e.g., _Host.cshtml) and can be used for login/logout redirect pages.

MVC Controllers

Enable with AddControllersWithViews = true:

{
  "BlazorServerStartupOptions": {
    "AddControllersWithViews": true
  }
}

When authentication is also enabled, AutoValidateAntiforgeryTokenAttribute is applied globally to all controller actions.

Controller endpoints are mapped via endpoints.MapControllers().

Project Layout

MyBlazorApp/
├── Pages/
│   ├── _Host.cshtml          # Application shell (required)
│   ├── _Layout.cshtml
│   ├── Index.razor
│   └── Counter.razor
├── Shared/
│   ├── MainLayout.razor
│   └── NavMenu.razor
├── wwwroot/
│   ├── css/
│   └── js/
├── Program.cs
├── Startup.cs
└── appsettings.json

Environment-Specific Behavior

Extending with Indiko Blocks

Blocks are resolved from the configuration and participate in the full lifecycle:

public override void ConfigureServices(IServiceCollection services)
{
    base.ConfigureServices(services); // blocks run here
    // additional registrations
}

Best Practices

• Keep ClientSecret out of source control — use environment variables, Azure Key Vault, or ASP.NET Core's Secret Manager.
• Enable ForceHttps and AddSecurityHeaderSupport together in Production.
• Set EnableForwardedHeaderOptions = true whenever the application runs behind a reverse proxy (nginx, Traefik, Azure Application Gateway, etc.).
• Do not enable CrossOriginEmbedderPolicy (COEP require-corp) in Development if you use Blazor hot reload, as it blocks cross-origin resources needed by the tooling.
• Call base.ConfigureServices(services) and base.Configure(app, environment, logger) from your overrides to retain all default wiring.

Target Framework

.NET 10

License

MIT — see LICENSE in the repository root.

Related Packages