AppSurface Auth Aspire Keycloak AppHost

This AppHost proves ForgeTrust.AppSurface.Auth.Aspire.Keycloak with real local Keycloak and a paired ASP.NET Core web app that uses ForgeTrust.AppSurface.Auth.AspNetCore.Oidc.

Five-Minute Real Login

Prerequisites:

• .NET 10 SDK
• Aspire CLI
• Docker or another Aspire-supported container runtime
• ports 8080 and 5059 available

Run the local graph:

AUTH_ASPIRE_KEYCLOAK_ENABLE_LOCAL_SEEDS=true aspire run --project examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- local

Open http://localhost:5059, choose sign in, and use one of the local-only seeded users:

Noninteractive verification:

AUTH_ASPIRE_KEYCLOAK_ENABLE_LOCAL_SEEDS=true aspire run --project examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- verify

The verifier checks Keycloak metadata, generated realm/client evidence, forbidden secret markers in the realm evidence, the authorization challenge, /auth/proof/status, /auth/proof/protected, and the exact consumer-owned result of the two local seed projects.

Ordered Local Seed Proof

This sample demonstrates the public ordered-local-seed extension points introduced for issue #782. The package owns only the readiness and completion graph. The sample owns the Keycloak Admin API call, the credentials, the durable local state, idempotence, and the fixture mutation:

The sample requires AUTH_ASPIRE_KEYCLOAK_ENABLE_LOCAL_SEEDS=true for every command that registers the mutating workers. That is an intentional sample-level opt-in for a non-default AppHost environment; without it, the package's Development/Test/Testing policy fails closed before either worker is materialized. Aspire Publish remains denied even when this flag is present.

Keycloak healthy
    -> package-owned RealmReady verifies metadata + realm evidence + public-client challenge
        -> auth-aspire-keycloak-seed-identity-bootstrap upserts local-broker and founder -> subject-founder-001
            -> auth-aspire-keycloak-seed-candidate-fixture upserts candidate:founder
                -> web proof and verifier start

The identity-bootstrap project alone receives the typed secret administrator-password parameter. The package never resolves that value, and neither the web proof nor fixture project receives its parameter reference. The workers write only non-secret records to .appsurface/auth-aspire-keycloak-local-seed-store.json below the AppHost directory. Before the identity worker sends its administrator-password grant, it accepts only the AppHost-projected HTTPS localhost or 127.0.0.1 authority whose path is exactly /realms/{realm}. A remote host, HTTP authority, encoded path separator, or realm mismatch fails locally before any administrator credential reaches transport.

The AppHost uses persistent Keycloak data deliberately. Each worker converges by a natural key, so a normal rerun leaves exactly one local-broker alias, one founder -> subject-founder-001 mapping, and one candidate:founder fixture. To prove safe partial recovery, inject the fixture failure after the first worker has converged:

AUTH_ASPIRE_KEYCLOAK_INJECT_FIXTURE_FAILURE=true \
  AUTH_ASPIRE_KEYCLOAK_ENABLE_LOCAL_SEEDS=true aspire run --project examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- verify

The candidate fixture ends nonzero; Aspire leaves the web proof blocked and no fixture record is written. Stop that intentional failed run, then run the normal verify command again. The idempotent first worker repairs or preserves its records, the fixture is added once, and the verifier proves the final counts. A hung consumer has no successful completion signal either, so its dependents stay blocked until the AppHost is canceled.

For focused, container-free API and graph coverage, run:

dotnet test Auth/ForgeTrust.AppSurface.Auth.Aspire.Keycloak.Tests/ForgeTrust.AppSurface.Auth.Aspire.Keycloak.Tests.csproj -p:UseSharedCompilation=false

This is startup-time local convergence against a real provider, not request-time persona selection. Use ForgeTrust.AppSurface.Auth.AspNetCore.DevAuth for visible fake personas during local requests, and use the paired ForgeTrust.AppSurface.Auth.AspNetCore.Oidc package for the web application's real OIDC registration.

Theme Lifecycle

The default sample intentionally stays on the no-theme path so a real OIDC login remains a five-minute proof. To activate its checked-in assets-only appsurface-sample theme, set an immutable Keycloak image reference before running the same local profile:

export AUTH_ASPIRE_KEYCLOAK_THEME_IMAGE='quay.io/keycloak/keycloak:26.6@sha256:22c8cf9e79af88d320499c93994bb2c319ca255092d8ae7c7a45dd46d68192e2'
AUTH_ASPIRE_KEYCLOAK_ENABLE_LOCAL_SEEDS=true aspire run --project examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- local

The package handles local read-only mounting, development-only cache switches, realm loginTheme selection, source manifest generation, and an immutable-image-ready build contract. See the package theme quickstart, build contract, CI evidence, and upgrade/rollback procedure.

Keep production image build/push, realm mutation, rollout, and rollback in application CI and operator runbooks. A bind mount and disabled theme caches are local-development behavior only.

Sample-theme acceptance

The checked-in appsurface-sample theme is intentionally assets-only: Keycloak retains its login templates and semantic form behavior. Before treating a pinned-image run as release evidence, record these manual checks against the local login page:

• keyboard-only sign-in and recovery reach visible focus indicators in logical tab order;
• invalid credentials, required actions, and expired-action recovery retain labels and Keycloak error association;
• browser zoom at 200%, a narrow viewport, and the no-CSS fallback leave the sign-in form usable;
• body/control contrast, screen-reader names for the logo, and reduced-motion behavior are acceptable;
• locale, RTL, dark-palette, and third-party-provider pages remain Keycloak/application-owned unless the consumer explicitly supplies and reviews those assets.

This checklist verifies the user-facing inherited states that manifest hashes cannot prove. Record the final image, source and packaged-manifest digests, build-contract digest, pinned base image, reviewer/date, and the matching keycloak-theme-evidence artifact alongside the result. The CI job runs the disposable-realm readback and same-origin stylesheet hash check; it never replaces this manual accessibility review.

State ownership matrix

The sample is an assets-only theme with an application-owned light palette. It inherits Keycloak templates, form semantics, and its no-CSS fallback. Its stylesheet has no logo or provider label, so application identity remains optional rather than impersonating an identity provider.

Recovery

This is not a production Keycloak administration sample. It does not teach social IdPs, confidential clients, tenant mapping, app-user provisioning, or provider lifecycle.