Blazor Behind Nginx – Addendums

This document is intended as add-on material to the main article:
“Fixing Blazor Apps Behind Nginx: Reverse Proxy Headers, WebSockets, and Redirect Hell”.

It covers:

• Blazor WebAssembly–specific considerations
• Hosting Blazor under a sub-path (e.g. /dashboard)

---

Addendum 1: Blazor WebAssembly Behind Nginx

Blazor WebAssembly (WASM) behaves very differently from Blazor Server when placed behind Nginx — mostly because there is no persistent server connection.

What Problems Go Away with Blazor WASM

Because Blazor WASM runs entirely in the browser:

• No SignalR
• No WebSockets
• No long-lived server connections
• No proxy timeouts freezing the UI

This removes an entire class of reverse-proxy issues.

However, redirects, auth, and absolute URLs can still break if forwarded headers are incorrect.

---

Minimal Nginx Config for Blazor WASM

location / {
    proxy_pass http://127.0.0.1:5000;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
}

No WebSocket upgrades or extended timeouts are required.

---

When Blazor WASM Still Breaks

Common failure modes:

OAuth / OIDC Redirect Failures

• Wrong scheme (http vs https)
• Incorrect host
• Missing forwarded headers

API Calls Fail

• Absolute URLs generated incorrectly
• CORS misconfiguration
• Hardcoded ports or protocols

Mixed Content Errors

• App served over HTTPS, APIs resolving to HTTP

These are still proxy metadata problems — not Blazor problems.

---

When WASM Is the Better Choice

Choose Blazor WASM if:

• You don’t need server push
• You don’t need per-user server state
• You want simpler infrastructure
• You want fewer reverse-proxy edge cases

Choose Blazor Server if:

• You need tight server control
• You need real-time server interaction
• You’re willing to manage WebSockets correctly

---

Addendum 2: Hosting Blazor Under a Sub-Path

Hosting Blazor under a sub-path instead of / introduces additional complexity.

Example:

• Public URL: https://example.com/dashboard
• Kestrel app: running at /

This requires explicit configuration in both Nginx and Blazor.

---

Nginx Sub-Path Proxy Configuration

location /dashboard/ {
    proxy_pass http://127.0.0.1:5000/;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;

    proxy_redirect off;
}

Key points:

• Trailing slashes matter
• proxy_redirect off prevents broken Location headers
• The path must be consistent everywhere

---

Blazor Server: Configure PathBase

app.UsePathBase("/dashboard");

This must be applied before routing and endpoints.

Missing this results in:

• Broken navigation
• Incorrect links
• Static asset failures

---

Blazor WASM: Configure Base Href

In wwwroot/index.html:

<base href="/dashboard/" />

If incorrect:

• Routing fails
• Static assets 404
• JS interop breaks

---

Authentication Cookie Gotchas

When hosting under a sub-path, cookies may not be sent correctly.

Symptoms:

• Login works once
• Refresh logs the user out
• Auth state disappears unexpectedly

Root causes:

• Cookie path mismatch
• Incorrect redirect URIs
• Missing PathBase configuration

(This is covered fully in the Keycloak deep dive.)

---

Common Sub-Path Failure Matrix

Symptom	Likely Cause
Navigation breaks	Missing PathBase or base href
Static assets 404	Trailing slash mismatch
Login loop	Cookie path mismatch
Redirects drop sub-path	Proxy redirect rewriting
API calls hit wrong URL	Absolute path assumptions

---

Recommendation

If possible, avoid sub-path hosting.

Prefer subdomains instead:

dashboard.example.com
api.example.com

This dramatically reduces routing, auth, and proxy complexity.

---