09 Keycloak Configuration

09 Keycloak Configuration — StartKeycloak.Tool (V81 Edition)

This page documents the official and supported way to run and configure Keycloak for BlazorKeycloak using the compiled bootstrap utility:

StartKeycloak.Tool

This tool provides a deterministic, idempotent bootstrap pipeline that behaves the same on:

• Windows (Docker Desktop)
• Linux (CI)
• macOS (Docker Desktop)

It ensures Keycloak is always in a known-good, reproducible state.

What StartKeycloak.Tool Automates

The tool fully automates:

• Realm creation
• Roles and client roles
• User provisioning
• Redirect and logout URIs
• Authorization Code + PKCE client setup
• Audience configuration for the Web API
• Client secret generation and persistence
• HTTPS vs HTTP environment detection

Manual Keycloak configuration is not supported.

🚀 Starting Keycloak (Development)

From the BlazorKeycloak repository root:

dotnet run --project StartKeycloak.Tool --

What This Command Does

1. Ensures Docker is running (Windows, best effort)
2. Starts or reuses the bk-keycloak container
3. Waits for Keycloak readiness (/.well-known/openid-configuration)
4. Ensures realm, users, roles, and clients exist
5. Validates redirect and logout URIs
6. Ensures Weather API audience mapper
7. Retrieves or rotates the client secret
8. Writes the secret to disk
9. Prints a deterministic summary

Running the tool multiple times is safe.

Client Secret Persistence

The confidential client secret is written to:

kc-client-secret.txt

This file is consumed by:

• Blazor Server
• ScriptTests
• Playwright E2E tests
• CI pipelines

If this file is missing or stale, authentication will fail.

What the Tool Ensures

Area	Ensured State
Realm	blazor-server
Realm roles	app-admin, app-user
Client	blazor-client (confidential, Auth Code + PKCE)
API client	weather-api (bearer-only)
Redirect URIs	App root + /signin-oidc
Post-logout URIs	App root + /signout-callback-oidc
Audience mapper	aud = weather-api
Users	bkadmin, alice, bob
Client secret	Persisted to disk

End-to-End Bootstrap Sequence (Developer → Docker → Keycloak)

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Tool as StartKeycloak.Tool
    participant Docker as Docker
    participant KC as Keycloak
    participant AdminApi as KC Admin API
    participant FS as File System

    Dev->>Tool: dotnet run
    Tool->>Docker: docker info
    Tool->>Docker: docker run / start (bk-keycloak)
    Tool->>KC: Wait for readiness
    Tool->>AdminApi: Admin login
    Tool->>AdminApi: Ensure realm, users, roles, clients
    Tool->>AdminApi: Get or rotate client secret
    Tool->>FS: Write kc-client-secret.txt
    Tool-->>Dev: Print summary

Loading

Internal Structure (Conceptual)

StartKeycloak.Tool is composed of focused responsibilities:

• StartKeycloakApp — composition root
• KeycloakLifecycle — Docker + readiness
• KeycloakProvisioning — realm, clients, users, roles
• ProcessRunner — docker execution
• ConsoleStyling — structured logging
• RepoLayout — repo root discovery
• BootstrapResult — immutable summary

Each component is testable and deterministic.

Example Run Output

[KC] Up. [KC] Client secret for 'blazor-client': …OJHoWW [KC] Verify write: kc-client-secret.txt (37 bytes)

─── [KC] Summary ───────────────────────── Upserted: • Password for 'bkadmin' • Password for 'alice' • Password for 'bob' No-Op: • Realm 'blazor-server' • Roles exist • Client 'blazor-client' Failures: (none) ──────────────────────────────────────────

Local Development Configuration

Item	Value
Admin Console	https://localhost:8443/admin
Realm	blazor-server
App client	blazor-client
API audience	weather-api
Redirect URIs	https://localhost:7261/, /signin-oidc
Post-logout URIs	https://localhost:7261/, /signout-callback-oidc
Web origins	https://localhost:7261
Demo users	bkadmin, alice, bob
Secret file	kc-client-secret.txt

PKCE Reminder

Keycloak 26+ always enforces PKCE for Authorization Code Flow.

There is:

• no toggle
• no setting
• no opt-out

This is the secure default and is relied upon by tests.

HTTPS (Dev) vs HTTP (CI)

StartKeycloak.Tool automatically adapts:

Environment	Base URL	Behavior
Local dev	https://localhost:8443	mkcert, TLS allowed
CI	http://localhost:8080	HTTP only
Production	Custom	Standard TLS

This keeps behavior consistent while simplifying CI.

Start / Stop / Reset (Local Development)

Start or reconfigure:

dotnet run --project StartKeycloak.Tool --

Stop container:

docker stop bk-keycloak

Remove container:

docker rm -f bk-keycloak

Reset database (destructive):

docker rm -f bk-keycloak
rm -r kc-data

Troubleshooting Highlights

If Keycloak is unreachable or auth fails:

• Re-run StartKeycloak.Tool
• Confirm kc-client-secret.txt exists
• Verify redirect URIs
• Check Diagnostics Hub
• Inspect Playwright traces before rerunning tests

Most issues are configuration drift.

Why StartKeycloak.Tool Matters

It provides:

• A single source of truth for identity configuration
• Guaranteed redirect and logout correctness
• Automatic PKCE and audience enforcement
• Deterministic local and CI behavior
• A fully test-backed configuration path

This is the only supported way to configure Keycloak for BlazorKeycloak.

Related Pages

• 03 Security Design
• 05 Role-Based Authorization
• 06 Access Control in Razor Components
• 12 Integration with the Web API
• 13 Developer Experience & Troubleshooting