Starter: Blazor Server + OpenIddict + protected API

A reusable starting point for .NET 10 web applications. Clone it (or generate a renamed copy with dotnet new) and start building features — sign-up, sign-in, sessions, API security, database, containers and tests are already in place.

• Solution structure
• Quick start
• How sign-in and API calls work
• Where to find things
• Running the tests
• Detailed documentation in docs/: architecture · security · local development · configuration · Google sign-in · extending the starter · testing · Azure deployment · maintenance and new apps
• UI style: design/STYLE-PROMPT.md

src/
  Starter.Identity    Identity server: accounts (ASP.NET Core Identity), OpenIddict, account pages (Razor Pages), Google
  Starter.Api         Web API: validates access tokens, owns business data (notes module)
  Starter.Web         Blazor Web App (Interactive Server): UI, OpenID Connect client, server-side sessions
  Starter.Contracts   Request/response models shared by the API and its clients
  Starter.Ui          Shared stylesheet (theme.css) used by the app and the account pages
tests/
  Starter.Api.Tests   Integration and security tests: real identity server + API in memory, SQL Server in a container
  Starter.E2E.Tests   Playwright (xUnit v3) end-to-end tests against a running environment
deploy/
  sql/                Database, schemas and least-privilege users (local SQL Server and Azure SQL)
  azure/              Bicep template for App Service, Azure SQL, Key Vault, registry, Application Insights
scripts/
  setup-local.cs      Creates local secrets, certificates and user secrets (run with `dotnet run`)

Why a separate identity server? It is the only component that sees passwords, talks to Google and issues tokens. The web app and a future mobile app are both ordinary OpenID Connect clients of it, and the API contains no UI and no cookies — it only validates tokens. See architecture.

Prerequisites: .NET 10 SDK, Docker (Docker Desktop on Windows/macOS), and once per machine:

dotnet dev-certs https --trust

(On Linux this command cannot configure every browser and tool; see local development → HTTPS.)

Create local secrets (.env, .certs/, user secrets — all git-ignored):

dotnet run scripts/setup-local.cs

docker compose --profile app up -d --build --wait

docker compose up -d --wait

Then start the three projects — in Visual Studio choose Configure Startup Projects → Multiple startup projects (Starter.Identity, Starter.Api, Starter.Web, profile https), or in three terminals:

dotnet run --project src/Starter.Identity --launch-profile https

dotnet run --project src/Starter.Api --launch-profile https

dotnet run --project src/Starter.Web --launch-profile https

In Development the apps apply their database migrations at startup.

Both variants use the same addresses, so OAuth redirect URIs and the Google callback URL are identical. Stop everything with docker compose --profile app down (add --volumes to delete the database).

sequenceDiagram
    autonumber
    participant B as Browser
    participant W as Starter.Web (Blazor Server)
    participant I as Starter.Identity (OpenIddict)
    participant A as Starter.Api
    B->>W: GET /notes (no session)
    W-->>B: 302 to /connect/authorize (code + PKCE)
    B->>I: sign in (password or Google)
    I-->>B: 302 to Web /signin-oidc?code=...
    B->>W: code
    W->>I: exchange code + PKCE verifier + client secret (server to server)
    I-->>W: access token (5 min), refresh token, id token
    W->>W: store tokens encrypted in the server-side session (SQL)
    W-->>B: __Host- session cookie (only a random session key)
    B->>W: UI interaction over the Blazor circuit (WebSocket)
    W->>A: API call with Bearer access token (added per request on the server)
    A->>A: validate signature, issuer, audience, expiry, scope; owner = sub
    A-->>W: data

• The browser never sees a token: it holds an HttpOnly, Secure, __Host- cookie with a random session key.
• Blazor components get the session key from the authentication state, not from HttpContext (which is not available inside an interactive circuit), load the token from the session store, refresh it when it is about to expire, and attach it to each individual API request.
• Sign-out deletes the server-side session, revokes the refresh token and ends the identity server session. An access token that was already issued stays valid until it expires (at most 5 minutes) but exists only on the server. Details and other limits: security.

How to add a protected page, an API endpoint and a new entity: docs/extending.md.

dotnet test --project tests/Starter.Api.Tests

Integration and security tests; needs Docker (SQL Server is started with Testcontainers).

dotnet test --project tests/Starter.E2E.Tests

Playwright tests; needs a running environment (variant 1 or 2) and the Playwright browser (pwsh tests/Starter.E2E.Tests/bin/Debug/net10.0/playwright.ps1 install chromium after the first build). Reports, traces and options: docs/testing.md.

The starter is verified locally in both variants (build, 60 integration tests, 15 Playwright tests, container images). The Azure template compiles but has not been deployed by the authors of this repository — treat docs/azure-deployment.md as a reviewed plan, not a tested release. Multi-instance operation is designed for (shared Data Protection keys and sessions in SQL) but not verified; see the scaling section there. Not included on purpose: admin panel, roles, two-factor authentication, account deletion.