ForgeTrust.AppSurface.Auth.Aspire.Keycloak 0.2.0-preview.8

ForgeTrust.AppSurface.Auth.Aspire.Keycloak

ForgeTrust.AppSurface.Auth.Aspire.Keycloak adds an AppHost-only local Keycloak proof for AppSurface OpenID Connect authentication. It builds on the official Aspire Keycloak hosting integration and keeps Keycloak, containers, and Aspire hosting dependencies out of runtime web app packages.

Use this package when you want a five-minute real OIDC login proof without signing up for SaaS, hand-configuring Keycloak, or copying fragile container setup between sample apps.

Use the AppSurface Auth adoption ladder when deciding whether this local real-provider proof, DevAuth, OIDC, Auth.Testing, or host-owned ASP.NET Core authentication is the right rung.

Do not use this package for production Keycloak administration, tenant authority, user provisioning, social identity providers, confidential-client secret lifecycle, app-user mapping, token storage, or provider SDK abstractions. Use ForgeTrust.AppSurface.Auth.AspNetCore.DevAuth for fake local personas and ForgeTrust.AppSurface.Auth.AspNetCore.Oidc when a web host already chose its OIDC provider.

Five-Minute Real Login

The focused repository proof uses a Keycloak AppHost and a paired web app:

aspire run --apphost examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- local

The web proof listens on http://localhost:5059. Sign in with one of the local-only seeded users:

The generated local users include a deterministic non-deliverable email address and surname. This satisfies Keycloak's default profile requirements, so the proof redirects directly after password sign-in instead of asking developers to complete a profile. These fields exist only in the disposable local realm and are not runtime configuration.

Run the noninteractive proof when a local container runtime is available:

aspire run --non-interactive --apphost examples/auth-aspire-keycloak-apphost/AuthAspireKeycloakAppHost.csproj -- verify

AppHost Shape

var keycloak = builder.AddAppSurfaceKeycloak();

var web = builder.AddProject<Projects.AuthAspireKeycloakWeb>("web")
    .WithHttpEndpoint(targetPort: AppSurfaceKeycloakDefaults.WebProofPort, env: "ASPNETCORE_HTTP_PORTS");

keycloak.Configuration.ApplyTo(web)
    .WithReference(keycloak.Resource)
    .WaitFor(keycloak.Resource);

AddAppSurfaceKeycloak(...) generates a deterministic realm import, calls the official Aspire AddKeycloak(...) API, mounts the realm import directory with WithRealmImport(...), and returns an AppSurfaceKeycloakResource wrapper whose Resource property exposes the underlying IResourceBuilder<KeycloakResource> for normal Aspire APIs.

Theme Quickstart

The original no-theme path stays the fastest proof. Opt into a local application-owned login theme only after pinning the Keycloak image you intend to test:

var themeSource = Path.GetFullPath("../Identity/KeycloakTheme", AppContext.BaseDirectory);
var loginTheme = AppSurfaceKeycloakThemeOptions.Login(
    name: "application",
    sourceDirectory: themeSource,
    baseImage: AppSurfaceKeycloakImageReference.Parse(
        "quay.io/keycloak/keycloak:26.6@sha256:<64-lowercase-hex-digest>"));
loginTheme.RequiredThemeProperties.Add("parent");
loginTheme.RequiredResourcePaths.Add("login/resources/css/site.css");

var keycloak = builder.AddAppSurfaceKeycloak("auth", options => options.LoginTheme = loginTheme);

Relative theme paths are resolved against the AppHost process base directory. Resolve them explicitly, as shown, or copy the theme into the AppHost output tree before registration.

The source root contains login/theme.properties and is mounted read-only at /opt/keycloak/themes/application. The local AppHost disables only Keycloak's theme and template caches. The mount intentionally reflects source edits for local development, while keycloak.Theme evidence captures the registration-time manifest only. It selects loginTheme in the generated disposable realm import and returns safe evidence containing the name, image reference, platform, and source-manifest digest. That evidence never exposes the source-machine path, property values, realm JSON, bootstrap credentials, or token material.

LoginTheme is optional. When it is absent, resource image configuration, realm JSON, and the existing five-minute local login behavior remain unchanged. The initial exact-image proof platform is linux/amd64; a different value is rejected instead of being silently presented as release evidence.

Source Policy

A theme source is a bounded regular-file tree rooted at login/theme.properties. The validator rejects missing roots, symbolic links/reparse points, traversal, unsupported files, more than 256 files or directories, individual files larger than 1 MiB, and trees larger than 8 MiB. Allowed files are Keycloak theme resources: .properties, .ftl, CSS, JavaScript, standard image formats, and common font formats.

The manifest sorts slash-normalized relative paths ordinally and records each file's byte length and SHA-256 digest; its digest is independent of machine-local source paths and file enumeration order. RequiredThemeProperties checks only property names, never serializes their values. RequiredResourcePaths and DevelopmentOnlyResourcePaths must resolve inside the manifest. The complete source manifest retains development-only assets as local evidence, while AppSurfaceKeycloakThemeBuildContract.PackagedManifest excludes them from the immutable image context and packaged-content proof. login/theme.properties cannot be development-only because a packaged Keycloak theme requires it.

Template Overrides

An assets-only theme needs no template baseline. A theme that copies a FreeMarker (.ftl) file must set TemplateBaselineDirectory to a reviewed, bounded upstream baseline containing the same slash-relative template paths. The registration records the baseline digest alongside the image and source-manifest digests, and rejects any copied template that is not present in that baseline. This detects unexpected template overrides before packaging; review and refresh the baseline whenever the pinned Keycloak image changes.

The baseline is evidence, not automatic migration. AppSurface never edits a FreeMarker template, changes Keycloak-owned form semantics, or claims a newer Keycloak image is compatible without a reviewed baseline and exact-image verification.

Build Contract

Use AppSurfaceKeycloakThemeBuildContract to create the consumer-owned immutable image context:

var buildContract = AppSurfaceKeycloakThemeBuildContract.Create(loginTheme);
var buildContext = buildContract.Write("artifacts/keycloak-theme");

// Application or CI owns this command, image tag, registry, and rollout.
// docker build --file "$buildContext/Containerfile" --tag application-keycloak:local "$buildContext"

buildContract.VerifyPackagedTheme(Path.Join(buildContext, "themes", "application"));

The fresh output directory contains a source snapshot under themes/<name> without development-only assets, a Containerfile, and an appsurface-keycloak-theme-manifest.json evidence file containing both source and packaged manifests. Digest binds the registration, both manifests, platform, base image, and template baseline. The Containerfile labels the theme name, source and packaged manifests, build-contract digest, base image, and platform. VerifyPackagedTheme fails if content is missing, added, or changed. The package does not build or push the image, mutate a production realm, deploy infrastructure, or automate rollout/rollback; those remain application and operations responsibilities.

For a mutable source, recreate the build contract immediately before packaging. A source change after registration makes build-context materialization fail before it copies an unproven file into the image context.

Release Evidence

After an application-owned CI build produces its digest-pinned theme image, bind it to the validated source and packaged manifests before any realm selection:

var releaseEvidence = AppSurfaceKeycloakThemeReleaseEvidence.Create(
    buildContract,
    "registry.example/appsurface-keycloak-theme:1.0@sha256:<64-lowercase-hex-digest>");
releaseEvidence.Write("artifacts/keycloak-theme-evidence.json");

The atomically written tuple records the theme name, source and packaged-manifest digests, build-contract digest, pinned Keycloak base image, final image, platform, and optional template-baseline digest. It excludes realm JSON, credentials, property values, source-machine paths, and image layers. Applications should publish the tuple with their CI artifact, then select the matching realm theme only after the image is available. Call Verify(...) before reusing a tuple to reject a changed image or build contract.

Theme Verification

There are two distinct proofs. The local AppHost proof mounts mutable source read-only and disables only development theme caches; it is for fast iteration and never release evidence. The immutable proof builds a fresh context, checks the image labels and exact theme subtree, starts a disposable Linux/amd64 Keycloak realm, reads back loginTheme, renders an authorization challenge, and hash-checks a declared same-origin resource. The package owns the deterministic inputs and evidence format. Application CI owns Docker, image publication, and the disposable runtime invocation.

An assets-only theme inherits Keycloak's templates and form semantics. A copied FreeMarker template remains subject to the reviewed baseline policy, and a Keycloak-image change always requires the upgrade procedure.

CI Evidence

The repository's required keycloak-theme-evidence job proves the checked-in sample against quay.io/keycloak/keycloak:26.6@sha256:22c8cf9e79af88d320499c93994bb2c319ca255092d8ae7c7a45dd46d68192e2 on Linux/amd64. It uploads a keycloak-theme-evidence artifact with pass, fail, or not-run status, safe manifest and build-contract digests, a candidate OCI manifest digest, and no credentials, realm import, source path, or image layer. not-run and fail are release-gate failures. A consuming release must replace the candidate image digest with its pushed immutable registry reference before calling AppSurfaceKeycloakThemeReleaseEvidence.Create.

This job is deliberately not production automation. It neither pushes the image nor mutates a production realm. Use the compatible tuple and order in the upgrade and rollback procedure for those application-owned operations.

Upgrade and Rollback

Treat the theme name, source manifest, packaged manifest, build-contract digest, final image digest, pinned Keycloak base image, platform, and template baseline as one compatible tuple. Publish and health-check the new image before selecting its theme. To roll back, restore the earlier verified image first, select the theme from its matching tuple, read back the selection and declared resource, record rollback evidence, then retain the former image until the rollback window closes. See the ordered upgrade and rollback procedure for the full checklist and template-baseline requirements.

Defaults

The paired web app receives only:

{
  "Authentication:Oidc:Authority": "https://localhost:8080/realms/appsurface-dev",
  "Authentication:Oidc:ClientId": "appsurface-web",
  "Authentication:Oidc:CallbackPath": "/signin-appsurface-oidc",
  "Authentication:Oidc:SignedOutCallbackPath": "/signout-callback-appsurface-oidc",
  "Authentication:Oidc:RequireClientSecret": "false"
}

The local Keycloak authority is HTTPS because Aspire publishes its browser-facing Keycloak endpoint over TLS, while the paired web proof remains HTTP on its fixed loopback port.

Admin credentials, seeded user passwords, raw realm JSON, tokens, client secrets, provider response bodies, and raw claims are never projected into runtime app configuration.

Persistent-data Recovery

Disposable data is the default because Keycloak startup realm import is deterministic on repeat runs. UsePersistentDataVolume = true keeps Keycloak data outside the container lifecycle; it also preserves admin credentials and imported realm state. If you change users, redirect URIs, or admin credentials while persistent data is enabled, delete the volume before expecting startup import to recreate the realm.

Diagnostics

Diagnostics use ASKEYC001+ codes and follow Problem/Cause/Fix/Docs wording. Common failures:

If the Aspire CLI is missing, install it before running the AppHost. If local development certificates block startup, run aspire certs trust or dotnet dev-certs https --trust from an interactive shell.

Escape Hatches

Use the underlying Aspire resource for ordinary local customization, a consumer-owned Containerfile for an application-owned image pipeline, or an assets-only theme for the smallest supported themed path. Non-amd64 and alternative runtimes may run deterministic source tests, but they cannot replace the named Linux/amd64 release proof. Production Keycloak, image publication, realm mutation, rollout, and rollback remain operator-owned and unsupported by this package.

Release Guidance

This AppHost-oriented package follows the coordinated AppSurface release policy. Before using a prerelease build in an AppHost, development, or test environment, check the package chooser and release hub for publication status, compatibility guidance, and readiness.

Back to Auth List | Back to Root