Add Keycloak with Postgres integration #811

axies20 · 2025-08-26T13:15:24Z

This PR introduces a new integration project that makes it easier to configure Keycloak to run with a Postgres database in Aspire-based applications.

Summary of changes

Added new project CommunityToolkit.Aspire.Keycloak.Postgres.

Implemented an extension method AddPostgres for IResourceBuilder to configure Keycloak with Postgres database resources:

Sets required environment variables (KC_DB, KC_DB_URL_*, KC_DB_USERNAME, KC_DB_PASSWORD, KC_TRANSACTION_XA_ENABLED).

Includes validation for missing or invalid Postgres server configuration.

Updated solution and package references to align with Aspire 9.4.1 dependencies.

Other information

Project name normalized to Postgres for correctness and consistency.

Extension method returns IResourceBuilder to allow chaining.

Uses proper IValueExpression instead of ToString() for connection strings.

Ensures JDBC-compatible environment variables for Keycloak.

- Introduced a new project `CommunityToolkit.Aspire.Keycloak.Postgress` for configuring Keycloak with PostgreSQL. - Added an extension method to simplify Keycloak and Postgres database resource integration. - Updated solution and package references for Aspire dependencies.

davidfowl · 2025-08-26T15:43:09Z

Did you test this?

- Enhanced parameter descriptions in XML documentation. - Updated method to support asynchronous operations. - Introduced additional environment variables for finer-grained database configuration. - Added cancellation token support for improved task management.

axies20 · 2025-08-26T19:25:40Z

I have some problems, i can't access host, can you help me?

- Simplified XML documentation and parameter descriptions. - Removed exceptions for parent resource validation. - Replaced manual environment variable setup with connection string parsing using `NpgsqlConnectionStringBuilder`. - Introduced optional port parameter for database configuration.

axies20 · 2025-08-26T22:30:10Z

Now it working

davidfowl · 2025-08-26T22:40:26Z

Its worth reading this https://github.com/dotnet/aspire/blob/main/docs/specs/appmodel.md#values-and-references

aaronpowell · 2025-08-27T04:49:27Z

Directory.Packages.props

  <ItemGroup Label="Aspire Packages">
    <!-- Aspire packages -->
-    <PackageVersion Include="Aspire.Hosting" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting" Version="9.4.1" />


I assume this is just done when you were testing, but ensure you roll that back and use the MSBuild variable

I had error
0>CommunityToolkit.Aspire.Keycloak.Postgres.csproj: Error NU1605 : Warning As Error: Detected package downgrade: Aspire.Hosting from 9.4.1 to 9.4.0. Reference the package directly from the project to select a different version.
CommunityToolkit.Aspire.Keycloak.Postgres -> Aspire.Hosting.Keycloak 9.4.1-preview.1.25408.4 -> Aspire.Hosting (>= 9.4.1)
CommunityToolkit.Aspire.Keycloak.Postgres -> Aspire.Hosting (>= 9.4.0)
0>------- Finished building project: CommunityToolkit.Aspire.Keycloak.Postgres. Succeeded: False. Errors: 1. Warnings: 0

The main branch is now updated to 9.4.1 Aspire.

aaronpowell · 2025-08-27T04:50:08Z

Once there are tests and samples, we can get started on a review of the work.

davidfowl · 2025-08-27T04:54:32Z

This implemenaton needs work:

You don't need to handle the event to make it work
This will only work when running but not when publishing.

See dotnet/aspire#8034 for more details.

Alirexaa

The package name should be CommunityToolkit.Aspire.Keycloak.Extensions, like other extension packages.

Alirexaa · 2025-08-27T09:31:48Z

...CommunityToolkit.Aspire.Keycloak.Postgress/CommunityToolkit.Aspire.Keycloak.Postgress.csproj

The package name should be CommunityToolkit.Aspire.Keycloak.Extensions, like other extension packages.

Can i name it like CommunityToolkit.Aspire.Keycloak.Extensions.Postgres?

I think there may be other providers here.

src/CommunityToolkit.Aspire.Keycloak.Postgress/KeycloakPostgresExtension.cs

…sExtension.cs Co-authored-by: Alireza Baloochi <alireza.baloochi1380@gmail.com>

- Renamed `CommunityToolkit.Aspire.Keycloak.Postgress` to `CommunityToolkit.Aspire.Keycloak.Extensions.Postgres`. - Refactored methods to improve flexibility, including support for different configurations (e.g., development, credentials). - Introduced a dedicated test project `CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests`. - Updated solution, dependencies, and project references accordingly.

axies20 · 2025-08-27T12:55:42Z

I updated, add event as dev and add parameters for production

davidfowl · 2025-08-27T18:32:06Z

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

+    /// <returns>
+    /// The updated resource builder for the Keycloak resource.
+    /// </returns>
+    private static void WithPostgres(this IResourceBuilder<KeycloakResource> builder,


This will work with dev and production.

You mean void? After that, you can't add other methods, so I returned IResourceBuilder

No, I mean that this approach using expressions works in both cases and you don’t need 2 implementations for run and publish

davidfowl · 2025-08-27T18:32:18Z

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

+    /// <returns>
+    /// The updated resource builder for the Keycloak resource.
+    /// </returns>
+    public static IResourceBuilder<KeycloakResource> WithPostgresDev(this IResourceBuilder<KeycloakResource> builder,


You don't need this overload at all.

You said that event will not work in prod, so I thought that this i will leave for the development environment

Right so you don’t need this

There can be conditional logic to check for the different modes rather than having to call different methods.

davidfowl · 2025-08-27T18:32:47Z

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

+            $"jdbc:postgresql://{ep.Property(EndpointProperty.Host)}:" +
+            $"{ep.Property(EndpointProperty.Port)}/{dbName}");
+
+        builder.WithEnvironment("KC_DB", "postgres")


Is this correct? Why is this hard coded?

What happens if postgres is password protected (which is the default).

builder.WithEnvironment("KC_DB", "postgres")
You about this? Yeah, it's correct. There are other database vendors, but I'm writing for postgres
All environment variables: https://www.keycloak.org/server/all-config
I wanna make for other vendors such as dev-file (default), dev-mem, mariadb, mssql, mysql, oracle, postgres (all vendors that support)

What happens if postgres is password protected (which is the default).

public static IResourceBuilder<KeycloakResource> WithPostgres(this IResourceBuilder<KeycloakResource> builder, IResourceBuilder<PostgresDatabaseResource> database, ParameterResource username, ParameterResource password) { ArgumentNullException.ThrowIfNull(username); ArgumentNullException.ThrowIfNull(password); WithPostgres(builder, database); builder.WithEnvironment("KC_DB_USERNAME", username) .WithEnvironment("KC_DB_PASSWORD", password); return builder; }

Here I'm setting by parameter that will set up from user, or what you mean?

aaronpowell

This is a hosting integration by the looks of it, so the project should reflect that.

Also, let's just make it Keycloak.Extensions so it's not PG specific, as that'll allow for other extensions on Keycloack to be included in here rather than going through a bunch of micro packages.

...ire.Keycloak.Extensions.Postgres/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.csproj

aaronpowell · 2025-08-28T00:44:22Z

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

+    /// <returns>
+    /// The updated resource builder for the Keycloak resource.
+    /// </returns>
+    public static IResourceBuilder<KeycloakResource> WithPostgresDev(this IResourceBuilder<KeycloakResource> builder,


There can be conditional logic to check for the different modes rather than having to call different methods.

aaronpowell · 2025-08-28T00:45:20Z

....Extensions.Postgres.Tests/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests.csproj

+    <PropertyGroup>
+        <TargetFramework>net9.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+        <IsPackable>false</IsPackable>
+    </PropertyGroup>


These aren't needed as they are inherited. Check the other test projects and follow their patterns

aaronpowell · 2025-08-28T00:45:37Z

....Extensions.Postgres.Tests/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests.csproj

+        <PackageReference Include="coverlet.collector" Version="6.0.2"/>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0"/>
+        <PackageReference Include="xunit" Version="2.9.2"/>
+        <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2"/>


These will fail the build as CPM dictates versions

aaronpowell · 2025-08-28T00:45:53Z

Directory.Packages.props

  <ItemGroup Label="Aspire Packages">
    <!-- Aspire packages -->
-    <PackageVersion Include="Aspire.Hosting" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting" Version="9.4.1" />


The main branch is now updated to 9.4.1 Aspire.

aaronpowell · 2025-08-28T00:47:13Z

Directory.Packages.props

    <PackageVersion Include="Aspire.Hosting.Dapr" Version="$(AspireVersion)" />
    <PackageVersion Include="Aspire.Hosting.Azure.AppContainers" Version="$(AspireVersion)" />
    <PackageVersion Include="Aspire.Hosting.Azure.Redis" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting.Keycloak" Version="9.4.1-preview.1.25408.4" />


We'll need to introduce a MSBuild variable for the preview version of Aspire packages.

aaronpowell · 2025-08-28T00:47:35Z

Directory.Packages.props

    <PackageVersion Include="Aspire.Hosting.MongoDB" Version="$(AspireVersion)" />
    <PackageVersion Include="Aspire.Hosting.MySql" Version="$(AspireVersion)" />
    <PackageVersion Include="Aspire.Hosting.SqlServer" Version="$(AspireVersion)" />
+    <PackageVersion Include="Moq" Version="4.20.72" />


This should be under the Testing item group

Copilot

Pull Request Overview

This PR introduces a new Keycloak-PostgreSQL integration that enables configuring Keycloak resources to use PostgreSQL databases within Aspire applications. The integration provides extension methods to set up the necessary JDBC connection strings and environment variables required by Keycloak to connect to PostgreSQL databases.

Extension methods for integrating Keycloak with PostgreSQL databases
Support for both development and production scenarios with different credential handling approaches
Package reference updates to align with Aspire 9.4.1 dependencies

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs	Core extension methods for Keycloak-PostgreSQL integration
src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.csproj	Project file with necessary Aspire package references
tests/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests/KeycloakExtensionPostgressTests.cs	Empty test class placeholder
tests/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres.Tests.csproj	Test project configuration
Directory.Packages.props	Updated Aspire package versions and added new dependencies
CommunityToolkit.Aspire.slnx	Solution file updated with new projects

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

Copilot · 2025-08-28T00:51:42Z

src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/KeycloakPostgresExtension.cs

+            builder.WithEnvironment("KC_DB", "postgres")
+                .WithEnvironment("KC_DB", "postgres")


The environment variable 'KC_DB' is being set twice with the same value 'postgres'. Remove the duplicate line 68.

Suggested change

builder.WithEnvironment("KC_DB", "postgres")

.WithEnvironment("KC_DB", "postgres")

…oakPostgresExtension.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

axies20 · 2025-08-28T11:22:13Z

 public static IResourceBuilder<KeycloakResource> WithPostgres(this IResourceBuilder<KeycloakResource> builder,
        IDistributedApplicationBuilder appBuilder, bool xaEnabled = false,
        string usernameParameter = "keycloak-username", string databaseName = "keycloak-db",
        string postgrsName = "keycloak-postgres")
    {
        var username = appBuilder.AddParameter(usernameParameter, "keycloak-db-user");
        var pwd = ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter(appBuilder, "pg-pass");
        var password = appBuilder.CreateResourceBuilder(pwd);
        var keycloakPostgres = appBuilder.AddPostgres(postgrsName, username, password);
        var db = keycloakPostgres.AddDatabase(databaseName);

        builder.WithPostgres(db, username, password, xaEnabled)
            .WithReference(db)
            .WaitFor(keycloakPostgres);
        return builder;
    }

What you think about this method for easy dev environment?

aaronpowell

I've gone ahead and fixed the outstanding issues and it's now ready to merge.

axies20 changed the title ~~**Add Keycloak with Postgres integration**~~ Add Keycloak with Postgres integration Aug 26, 2025

axies20 added 2 commits August 26, 2025 22:22

Merge branch 'main' into KeycloakPostgres

1bf7ea7

aaronpowell reviewed Aug 27, 2025

View reviewed changes

Alirexaa reviewed Aug 27, 2025

View reviewed changes

axies20 and others added 3 commits August 27, 2025 13:47

Update src/CommunityToolkit.Aspire.Keycloak.Postgress/KeycloakPostgre…

7a4fc17

…sExtension.cs Co-authored-by: Alireza Baloochi <alireza.baloochi1380@gmail.com>

Merge branch 'main' into KeycloakPostgres

03cbc0a

davidfowl reviewed Aug 27, 2025

View reviewed changes

aaronpowell requested changes Aug 28, 2025

View reviewed changes

aaronpowell changed the title ~~Add Keycloak with Postgres integration~~ [WIP] Add Keycloak with Postgres integration Aug 28, 2025

aaronpowell requested a review from Copilot August 28, 2025 00:50

Copilot AI reviewed Aug 28, 2025

View reviewed changes

axies20 and others added 4 commits August 28, 2025 12:10

Update src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/Keycl…

53c7ca1

…oakPostgresExtension.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/Keycl…

9c913c5

…oakPostgresExtension.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/CommunityToolkit.Aspire.Keycloak.Extensions.Postgres/Keycl…

d77acaf

…oakPostgresExtension.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/main' into KeycloakPostgres

fcfad00

Merge branch 'main' into KeycloakPostgres

6cd7d93

aaronpowell added 3 commits October 22, 2025 04:06

Adding the tests in

4a801e9

Fixing more bad changes

cab3674

Dealing with more build errors

1e5d94d

aaronpowell approved these changes Oct 22, 2025

View reviewed changes

Merge branch 'main' into KeycloakPostgres

5961fec

aaronpowell merged commit 04de150 into CommunityToolkit:main Oct 24, 2025
209 of 211 checks passed

This was referenced Nov 24, 2025

Bump the dotnet-minor-patch group with 24 updates DigiBanks99/menlo#116

Merged

Bump the aspire group with 6 updates dgee2/Menu#791

Closed

This was referenced Dec 16, 2025

Bump the aspire group with 6 updates dgee2/Menu#816

Closed

Bump Aspire.Hosting.AppHost and 4 others dgee2/Menu#818

Closed

Bump the aspire group with 6 updates dgee2/Menu#822

Open

		builder.WithEnvironment("KC_DB", "postgres")
		.WithEnvironment("KC_DB", "postgres")

Add Keycloak with Postgres integration #811

Add Keycloak with Postgres integration #811

Uh oh!

Conversation

axies20 commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidfowl commented Aug 26, 2025

Uh oh!

axies20 commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

axies20 commented Aug 26, 2025

Uh oh!

davidfowl commented Aug 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaronpowell commented Aug 27, 2025

Uh oh!

davidfowl commented Aug 27, 2025

Uh oh!

Alirexaa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

axies20 Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

axies20 commented Aug 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

axies20 Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaronpowell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

axies20 commented Aug 26, 2025 •

edited

Loading

axies20 commented Aug 26, 2025 •

edited

Loading

axies20 Aug 27, 2025 •

edited

Loading

axies20 Aug 27, 2025 •

edited

Loading

axies20 commented Aug 28, 2025 •

edited

Loading