AppSurface Search
Section API Reference
API Reference Language: C# Component: Auth Audience: developer

Keycloak

Type

AppSurfaceKeycloakHostingExtensions

Source

Adds AppSurface local Keycloak proof resources to Aspire AppHosts.

Method

AddAppSurfaceKeycloak

AppSurfaceKeycloakResource AddAppSurfaceKeycloak(this IDistributedApplicationBuilder builder, string name = AppSurfaceKeycloakDefaults.ResourceName, Action<AppSurfaceKeycloakOptions>? configure = null) Source

Adds an official Aspire Keycloak resource configured with deterministic AppSurface local OIDC proof defaults.

Parameters

  • builderThe distributed application builder.
  • nameThe Aspire resource name.
  • configureOptional callback that customizes local proof options.

Returns

An AppSurface wrapper exposing the underlying Keycloak resource, secret-safe config projection, and readiness probe.

Type

AppSurfaceKeycloakException

Source

Represents a safe AppSurface Keycloak proof diagnostic with a stable code.

Property

Code

string Code { get; } Source

Gets the stable AppSurface Keycloak diagnostic code.

Type

AppSurfaceKeycloakReadinessResult

Source

Captures safe readiness evidence for the AppSurface Keycloak local proof.

Parameters

  • AuthorityThe verified Keycloak realm authority.
  • ClientIdThe verified public client id.
  • RealmThe verified realm id.
Type

AppSurfaceKeycloakRealmImportPaths

Source

Resolves safe local paths for generated Keycloak realm import artifacts.

Method

GetDefaultImportDirectory

string GetDefaultImportDirectory() Source

Gets the default realm import directory without creating it.

Returns

The default directory beneath the application base directory.

Method

ResolveImportDirectory

string ResolveImportDirectory(string rootDirectory, string resourceName) Source

Resolves a resource-specific realm import directory without creating it.

Parameters

  • rootDirectoryRoot directory that owns generated realm imports.
  • resourceNameResource name used as one safe path segment.

Returns

The resolved import directory.

Method

GetRealmImportFilePath

string GetRealmImportFilePath(string realmImportDirectory, string realm) Source

Resolves the generated realm import file beneath an import directory.

Parameters

  • realmImportDirectoryDirectory that contains realm imports.
  • realmRealm id used in the generated file name.

Returns

The safe realm import file path.

Type

AppSurfaceKeycloakReadinessProbe

Source

Performs bounded, multi-signal readiness checks for the AppSurface local Keycloak proof.

Method

CheckOnceAsync

Task<AppSurfaceKeycloakReadinessResult> CheckOnceAsync(CancellationToken cancellationToken = default) Source

Checks metadata, generated realm evidence, and authorization challenge evidence once.

Parameters

  • cancellationTokenCancellation token for HTTP work.

Returns

A successful readiness result.

Type

AppSurfaceKeycloakDiagnosticCodes

Source

Stable diagnostic codes emitted by the AppSurface Keycloak AppHost proof package.

Type

AppSurfaceKeycloakConfigurationProjection

Source

Secret-safe app configuration produced by the AppSurface Keycloak proof package.

Remarks

The projection only contains OIDC authority, client id, callback paths, and the public-client secret policy. It never contains admin credentials, seeded user passwords, realm JSON, tokens, raw claims, or client secrets.

Method

ApplyTo

IResourceBuilder<ProjectResource> ApplyTo(IResourceBuilder<ProjectResource> project) Source

Applies the allowlisted environment variables to an Aspire project resource.

Parameters

  • projectThe project resource builder.

Returns

The same project resource builder for chaining.

Property

Authority

string Authority { get; } Source

Gets the local Keycloak realm authority.

Property

ClientId

string ClientId { get; } Source

Gets the local public client id.

Property

CallbackPath

string CallbackPath { get; } Source

Gets the OIDC callback path.

Property

SignedOutCallbackPath

string SignedOutCallbackPath { get; } Source

Gets the OIDC signed-out callback path.

Property

RequireClientSecret

bool RequireClientSecret { get; } Source

Gets a value indicating whether the paired proof app should require a client secret.

Property

EnvironmentVariables

IReadOnlyDictionary<string, string> EnvironmentVariables { get; } Source

Gets the allowlisted environment variables used by the proof web app.

Type

AppSurfaceKeycloakOptions

Source

Configures the deterministic local Keycloak realm and public client used for AppSurface OIDC proof AppHosts.

Method

Validate

void Validate() Source

Validates all local Keycloak proof options and populates default redirect URIs when needed.

Method

CreateConfigurationProjection

AppSurfaceKeycloakConfigurationProjection CreateConfigurationProjection() Source

Builds the secret-safe configuration projection for the paired web proof.

Returns

An immutable projection containing only allowlisted OIDC configuration.

Property

Realm

string Realm { get; set; } Source

Gets or sets the local Keycloak realm name.

Property

ClientId

string ClientId { get; set; } Source

Gets or sets the local public OIDC client id.

Property

ClientDisplayName

string ClientDisplayName { get; set; } Source

Gets or sets the local display name imported for the OIDC client.

Property

CallbackPath

string CallbackPath { get; set; } Source

Gets or sets the OIDC callback path used by the web proof.

Property

SignedOutCallbackPath

string SignedOutCallbackPath { get; set; } Source

Gets or sets the OIDC signed-out callback path used by the web proof.

Property

KeycloakPort

int KeycloakPort { get; set; } Source

Gets or sets the fixed local Keycloak host port.

Property

WebProofPort

int WebProofPort { get; set; } Source

Gets or sets the fixed local web proof port used to build redirect URIs.

Property

UsePersistentDataVolume

bool UsePersistentDataVolume { get; set; } Source

Gets or sets a value indicating whether Keycloak data should persist in a container volume.

Remarks

Disposable data is the default so realm import is deterministic. Persistent data keeps admin credentials and imported realm state until the volume is deleted.

Property

RealmImportDirectory

string RealmImportDirectory { get; set; } Source

Gets or sets the directory that receives generated Keycloak realm import JSON.

Property

RedirectUris

IList<Uri> RedirectUris { get; } Source

Gets mutable redirect URIs imported into the public OIDC client.

Property

PostLogoutRedirectUris

IList<Uri> PostLogoutRedirectUris { get; } Source

Gets mutable post-logout redirect URIs imported into the public OIDC client.

Property

SeededUsers

IList<AppSurfaceKeycloakUserOptions> SeededUsers { get; } Source

Gets mutable local-only users imported into the proof realm.

Type

AppSurfaceKeycloakUserOptions

Source

Describes a deterministic local-only user imported into the AppSurface Keycloak proof realm.

Method

Validate

void Validate() Source

Validates the seeded user's username, subject, password, display name, and claim entries.

Exceptions

  • AppSurfaceKeycloakExceptionA seeded user option is invalid.
Property

Username

string Username { get; } Source

Gets the local Keycloak username.

Property

Password

string Password { get; } Source

Gets the temporary local-only password used by Keycloak realm import.

Remarks

This value is intentionally never included in runtime app configuration projection.

Property

Subject

string Subject { get; } Source

Gets the stable OIDC subject value.

Property

DisplayName

string DisplayName { get; } Source

Gets the local display name used by the proof UI.

Property

Claims

IDictionary<string, string> Claims { get; } Source

Gets local-only user attributes that should be imported and optionally mapped to claims.

Type

AppSurfaceKeycloakDefaults

Source

Default local-only values used by the AppSurface Keycloak AppHost proof package.

Remarks

These defaults intentionally mirror the AppSurface OIDC package callback paths without taking a runtime dependency on that package. Drift is covered by tests so the AppHost proof package does not become part of web auth registration.

Method

Authority

string Authority(string realm = Realm, int port = KeycloakPort) Source

Builds the default authority URL for a local realm and port.

Parameters

  • realmThe Keycloak realm name.
  • portThe local Keycloak host port.

Returns

The local HTTP authority URL.

Type

AppSurfaceKeycloakPortPreflight

Source

Provides early local fixed-port diagnostics before Aspire starts containers or projects.

Method

ThrowIfOccupied

void ThrowIfOccupied(int port, string optionName) Source

Throws a safe diagnostic when a configured fixed port is already occupied.

Parameters

  • portThe local TCP port to check.
  • optionNameThe option name that supplied the fixed port.
Method

IsAvailable

bool IsAvailable(int port) Source

Returns whether a local TCP port can be bound at preflight time.

Parameters

  • portThe local TCP port to check.

Returns

true when the port can be bound; otherwise false.

Type

AppSurfaceKeycloakRealmGenerator

Source

Generates deterministic Keycloak realm import JSON for the AppSurface local proof.

Method

Generate

string Generate(AppSurfaceKeycloakOptions options) Source

Generates deterministic realm import JSON from validated options.

Parameters

  • optionsThe Keycloak proof options.

Returns

A JSON document suitable for Keycloak startup realm import.

Method

WriteRealmImport

string WriteRealmImport(AppSurfaceKeycloakOptions options) Source

Writes deterministic realm import JSON into the configured import directory.

Parameters

  • optionsThe Keycloak proof options.

Returns

The written realm import file path.

Type

AppSurfaceKeycloakResource

Source

Wraps the official Aspire Keycloak resource with AppSurface local proof metadata.

Property

Resource

IResourceBuilder<KeycloakResource> Resource { get; } Source

Gets the underlying Aspire Keycloak resource builder for normal Aspire APIs such as WithReference and WaitFor.

Property

Configuration

AppSurfaceKeycloakConfigurationProjection Configuration { get; } Source

Gets the secret-safe web configuration projection.

Property

Readiness

AppSurfaceKeycloakReadinessProbe Readiness { get; } Source

Gets the readiness probe.

Property

RealmImportFile

string RealmImportFile { get; } Source

Gets the generated realm import file path.