Keycloak integration

🧪 Preview

Keycloak is an open-source Identity and Access Management solution aimed at modern applications and services. The Keycloak integration enables you to connect to existing Keycloak instances or create new instances from Aspire with the quay.io/keycloak/keycloak container image.

Hosting integration

The Keycloak hosting integration models the server as the KeycloakResource type. To access this type and APIs, add the 📦 Aspire.Hosting.Keycloak NuGet package in your AppHost project:

Aspire CLI

Aspire CLI — Add Aspire.Hosting.Keycloak package

aspire add keycloak

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> keycloak (Aspire.Hosting.Keycloak)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Keycloak@*

PackageReference (*.csproj)

XML — Add Aspire.Hosting.Keycloak package reference

<PackageReference Include="Aspire.Hosting.Keycloak" Version="*" />

Add Keycloak resource

In your AppHost, call AddKeycloak to add and return a Keycloak resource builder:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

const webfrontend = await builder.addProject("webfrontend", "../Web/Web.csproj");
await webfrontend.withExternalHttpEndpoints();
await webfrontend.withReference(keycloak);
await webfrontend.withReference(apiService);
await webfrontend.waitFor(apiService);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080);

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

var webfrontend = builder.AddProject<Projects.Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(keycloak)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

Tip

For local development use a stable port for the Keycloak resource (8080 in the preceding example). It can be any port, but it should be stable to avoid issues with browser cookies that will persist OIDC tokens beyond the lifetime of the AppHost.

When Aspire adds a container image to the AppHost, it creates a new Keycloak instance on your local machine. The Keycloak resource includes default credentials:

• KEYCLOAK_ADMIN: A value of admin
• KEYCLOAK_ADMIN_PASSWORD: Random password generated using the default password parameter

When the AppHost runs, the password is stored in the AppHost’s secret store in the Parameters section:

{
  "Parameters:keycloak-password": "<THE_GENERATED_PASSWORD>"
}

Tip

If you’d rather connect to an existing Keycloak instance, call AddConnectionString instead. For more information, see Reference existing resources.

• Keycloak container imageQuay.io

  quay.io/keycloak/keycloak:26.6

  Added by AddKeycloak()addKeycloak().

  Source

Tags reflect the latest defaults on the microsoft/aspire main branch, and may be newer than the version pinned by the package you install.

Add Keycloak resource with data volume

To add a data volume to the Keycloak resource, call the WithDataVolume method on the Keycloak resource:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });
await keycloak.withDataVolume();

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithDataVolume();

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

The data volume is used to persist the Keycloak data outside the lifecycle of its container. The data volume is mounted at the /opt/keycloak/data path in the Keycloak container.

Caution

The admin credentials are stored in the data volume. When using a data volume and if the credentials change, it will not work until you delete the volume.

Add Keycloak resource with data bind mount

To add a data bind mount to the Keycloak resource, call the WithDataBindMount method:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });
await keycloak.withDataBindMount("/path/to/keycloak/data");

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithDataBindMount(@"C:\Keycloak\Data");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

Note

Data bind mounts have limited functionality compared to volumes, and when you use a bind mount, a file or directory on the host machine is mounted into a container. Bind mounts are best suited to local development and testing.

Add Keycloak resource with parameters

When you want to explicitly provide the admin username and password used by the container image, you can provide these credentials as parameters:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const username = await builder.addParameter("username");
const password = await builder.addParameter("password", { secret: true });

const keycloak = await builder.addKeycloak("keycloak", {
  port: 8080,
  adminUsername: username,
  adminPassword: password,
});

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var keycloak = builder.AddKeycloak("keycloak", 8080, username, password);

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

For more information on providing parameters, see External parameters.

Add Keycloak resource with realm import

To import a realm into Keycloak, call the WithRealmImport method:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });
await keycloak.withRealmImport("./Realms");

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithRealmImport("./Realms");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

The realm import files are copied to /opt/keycloak/data/import in the Keycloak container. Realm import files are JSON files that represent the realm configuration.

Caution

WithRealmImport is intended for local development. It uses development-time container file injection and isn’t supported when publishing or deploying the AppHost with aspire publish or aspire deploy. For production deployments, bake realm files into a custom image or seed Keycloak from an initialization process. This is the current behavior for the Keycloak integration; check the release notes for future changes.

Production alternatives for realm seeding

For production environments, consider these alternatives to seed your Keycloak instance:

Custom Keycloak image: Bake realm files into a custom image. Apply WithDockerfile to the Keycloak resource instead of replacing AddKeycloak with AddContainer:

keycloak/Dockerfile

FROM quay.io/keycloak/keycloak:25.0.0
COPY ./realms/*.json /opt/keycloak/data/import/

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });
await keycloak.withDockerfile("./keycloak");

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithDockerfile("./keycloak");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

TypeScript

Directory layout

apphost.mts
keycloak/
  Dockerfile
  realms/
    demo-realm.json

C#

Directory layout

AppHost.cs
keycloak/
  Dockerfile
  realms/
    demo-realm.json

Tip

This approach keeps the defaults that AddKeycloak applies, including the Keycloak startup arguments. You don’t need an extra WithArgs("start", "--import-realm") call when you keep using AddKeycloak.

Initialization service: Create a separate initialization service or job that uses the Keycloak Admin REST API or Keycloak Admin Client to create and configure realms, clients, and users when the Keycloak instance first starts.

Infrastructure as Code: Use tools like Terraform with the Keycloak provider to manage realm configuration separately from your application deployment.

Export telemetry to OTLP collector

Keycloak containers can export telemetry to your OTLP collector using the WithOtlpExporter method:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const keycloak = await builder.addKeycloak("keycloak", { port: 8080 });
await keycloak.withOtlpExporter();

const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
await apiService.withReference(keycloak);
await apiService.waitFor(keycloak);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithOtlpExporter();

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(keycloak)
    .WaitFor(keycloak);

builder.Build().Run();

This enables Keycloak to send traces, metrics, and logs to the Aspire dashboard, providing better observability for your authentication flows.

Use PostgreSQL with the Community Toolkit extension

⭐ Community Toolkit

The 📦 CommunityToolkit.Aspire.Hosting.Keycloak.Extensions package decorates the official KeycloakResource with WithPostgres / withPostgres. It configures Keycloak to use an official PostgresDatabaseResource, supplies the JDBC URL and credentials, and makes Keycloak wait for the database.

Aspire CLI

Aspire CLI — Add CommunityToolkit.Aspire.Hosting.Keycloak.Extensions package

aspire add communitytoolkit-keycloak-extensions

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> communitytoolkit-keycloak-extensions (CommunityToolkit.Aspire.Hosting.Keycloak.Extensions)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.Keycloak.Extensions@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.Hosting.Keycloak.Extensions package reference

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Keycloak.Extensions" Version="*" />

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const postgres = await builder.addPostgres('keycloak-postgres');
const database = await postgres.addDatabase('keycloakdb');

const keycloak = await builder.addKeycloak('keycloak', { port: 8080 });
await keycloak.withPostgres(database);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("keycloak-postgres");
var database = postgres.AddDatabase("keycloakdb");

var keycloak = builder.AddKeycloak("keycloak", 8080)
    .WithPostgres(database);

builder.Build().Run();

By default, WithPostgres uses the PostgreSQL server’s username and password parameters. Its optional arguments let you supply different username and password parameter resources and set xaEnabled when Keycloak needs XA transactions.

Hosting integration health checks

The Keycloak hosting integration automatically adds an HTTP health check against the management endpoint’s /health/ready path.

Client integration

To get started with the Keycloak client integration, install the 📦 Aspire.Keycloak.Authentication NuGet package in your ASP.NET Core project:

.NET CLI

.NET CLI — Add Aspire.Keycloak.Authentication package

dotnet add package Aspire.Keycloak.Authentication

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Keycloak.Authentication@*

PackageReference (*.csproj)

XML — Add Aspire.Keycloak.Authentication package reference

<PackageReference Include="Aspire.Keycloak.Authentication" Version="*" />

The Keycloak client integration registers JwtBearer and OpenId Connect authentication handlers in the DI container for connecting to a Keycloak server.

Add JWT bearer authentication

In the Program.cs file of your ASP.NET Core API project, call the AddKeycloakJwtBearer extension method to add JwtBearer authentication:

Program.cs

builder.Services.AddAuthentication()
    .AddKeycloakJwtBearer(
        serviceName: "keycloak",
        realm: "api",
        options =>
        {
            options.Audience = "store.api";

            // For development only - disable HTTPS metadata validation
            // In production, use explicit Authority configuration instead
            if (builder.Environment.IsDevelopment())
            {
                options.RequireHttpsMetadata = false;
            }
        });

Caution

When using RequireHttpsMetadata = true (the default), the JWT Bearer authentication requires the Authority URL to use HTTPS. However, Aspire service discovery uses the https+http:// scheme, which doesn’t satisfy this requirement. For production scenarios where HTTPS metadata validation is required, you need to explicitly configure the Authority URL.

Add OpenId Connect authentication

In the Program.cs file of your API-consuming project (for example, Blazor), call the AddKeycloakOpenIdConnect extension method to add OpenId Connect authentication:

Program.cs

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddKeycloakOpenIdConnect(
        serviceName: "keycloak",
        realm: "api",
        options =>
        {
            options.ClientId = "StoreWeb";
            options.ResponseType = OpenIdConnectResponseType.Code;
            options.Scope.Add("store:all");
        });

Production considerations

When deploying Keycloak authentication to production environments, there are several important security considerations:

HTTPS metadata requirements

By default, JWT Bearer authentication in ASP.NET Core has RequireHttpsMetadata = true, which requires that the Authority URL uses HTTPS.

For production scenarios, configure the Authority URL explicitly:

Program.cs

builder.Services.AddAuthentication()
    .AddKeycloakJwtBearer(
        serviceName: "keycloak",
        realm: "MyRealm",
        configureOptions: options =>
        {
            // Explicitly set the Authority for production
            if (!builder.Environment.IsDevelopment())
            {
                options.Authority = "https://your-keycloak-server.com/realms/MyRealm";
            }

            options.Audience = "my.api";
        });

Connection string configuration

For production deployments, consider using connection strings:

TypeScript

apphost.mts

import { createBuilder, refExpr } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

await builder.addConnectionString('keycloak', {
  environmentVariableNameOrExpression: refExpr`https://your-keycloak-server.com`,
});

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddConnectionString("keycloak", "https://your-keycloak-server.com");

builder.Build().Run();

Security best practices

• Always use RequireHttpsMetadata = true in production environments
• Use secure, validated SSL certificates for your Keycloak server
• Configure appropriate realm settings and client configurations in Keycloak
• Implement proper token validation and audience checks
• Consider using Keycloak’s built-in security features like rate limiting and brute force protection

See also

• Keycloak documentation
• 📦 Aspire.Hosting.Keycloak NuGet package
• 📦 Aspire.Keycloak.Authentication NuGet package
• External parameters