Blazor Server + Keycloak 26+ with PKCE, secure API access, automated setup, and full end-to-end validation — designed for Confidence Through Testing.
BlazorKeycloak is a:
- Self-provisioning development environment
- Complete learning platform for modern identity
- Fully tested authentication and authorization system
Built with Blazor Server and Keycloak 26+, it is designed so identity behavior is provable, not assumed.
If you want a system where:
- Identity always works
- TLS is correctly configured
- Keycloak boots deterministically
- PKCE is validated, not guessed
- API access is secure and testable
- Your environment is reproducible
BlazorKeycloak is designed for you.
By working with BlazorKeycloak, you will learn how to:
- Authenticate Blazor Server using OIDC Authorization Code Flow + PKCE
- Secure Web APIs with audience-limited access tokens
- Configure Keycloak programmatically: realms, users, roles, clients, and mappers
- Generate and trust mkcert HTTPS certificates for local development
- Use deterministic tooling as a source of truth
- Inspect tokens, claims, audiences, and system health via diagnostics
- Understand identity flows through diagrams tied directly to runtime behavior
- Run and interpret a comprehensive end-to-end test suite validating: login, PKCE, API access, logout, and diagnostics
Identity is taught by running real infrastructure and proving correctness with tests.
BlazorKeycloak includes a comprehensive White Paper that explains the architecture, security model, and design philosophy behind the project.
It describes why the system is structured the way it is — not just how to run it.
- 👉 Read the White Paper (Markdown):
docs/Whitepaper.md - 📥 Download PDF / DOCX: available in the
docs/folder
If you want to understand how deterministic setup, PKCE, Keycloak bootstrapping, and end-to-end validation fit together as a coherent system, start here.
BlazorKeycloak supports multiple audiences — from developers new to Keycloak to those already familiar with OIDC and identity systems.
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/01-Project-Overview
Project goals, structure, and how to approach the repository.
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/02-Keycloak-Concepts
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/03-Security-Design
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/04-Architecture-Diagrams
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/05-Role-Based-Authorization
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/06-Access-Control-in-Razor-Components
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/07-Setup-Quick-Start
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/08-Setup-Instructions
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/09-Keycloak-Configuration
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/10-Usage-Instructions
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/11-Tests-Guide
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/12-Integration-with-the-Web-API
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/13-Developer-Experience-and-Troubleshooting
- https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/14-Extending-BlazorKeycloak
BlazorKeycloak provides two complementary setup guides:
07 Setup – Quick Start
https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/07-Setup-Quick-Start
A short, opinionated guide that gets you from zero → running BlazorKeycloak using the recommended everyday development workflow.
08 Setup Instructions
https://github.com/GalaxyEClinical/BlazorKeycloak/wiki/08-Setup-Instructions
The single source of truth for fully automated, reproducible setup.
This guide:
- Verifies machine prerequisites
- Generates trusted HTTPS certificates using mkcert
- Boots and provisions Keycloak 26+
- Creates realms, users, roles, and clients
- Installs Playwright browsers
- Runs 70+ unit, integration, API, and end-to-end tests
After setup completes successfully, your environment is ready for development.
Modern identity systems are difficult:
- OIDC has a steep learning curve
- PKCE behavior varies across implementations
- TLS setup differs by OS
- Redirect URIs fail silently
- Audience mapping is non-obvious
- Identity provider configuration is fragile
- Documentation drifts from reality
BlazorKeycloak addresses this by:
- Automating configuration
- Enforcing secure defaults
- Validating behavior with tests
- Providing diagnostics instead of guesswork
- Making identity workflows deterministic
You don’t hope identity works — you prove it.
BlazorKeycloak is a self-validated identity platform for Blazor Server.
Automated setup, deterministic tooling, extensive tests, and a structured wiki combine to deliver: