Get started with the Zitadel integration

⭐ Community Toolkit

Zitadel is an identity and access management service that supports OpenID Connect, OAuth 2.0, and SAML. The Aspire Community Toolkit hosting integration runs a Zitadel container and configures its PostgreSQL dependency in your AppHost.

Use this integration to develop applications against a local identity provider. It configures the first administrator account, exposes the server endpoint, and reports server health in the Aspire dashboard.

Why use Zitadel with Aspire

• Declare Zitadel and PostgreSQL together instead of maintaining separate container startup scripts.
• Pass database credentials and allocated endpoints through resource references.
• Generate an administrator password and master key, or supply secret parameters.
• Wait for PostgreSQL before starting Zitadel, and wait for Zitadel’s health check before starting consumers.
• Use the exported hosting APIs from either a TypeScript or C# AppHost.

How the pieces fit together

flowchart LR
    AppHost[AppHost] --> Zitadel[Zitadel container]
    AppHost --> PostgreSQL[PostgreSQL container]
    Zitadel --> PostgreSQL
    App[Consuming app] -->|OpenID Connect| Zitadel
    Browser[Browser] -->|Sign in| Zitadel

The hosting package belongs in the AppHost. PostgreSQL stores Zitadel’s data, and Zitadel initializes the database when it starts. Your application uses an OpenID Connect library to authenticate users against the Zitadel endpoint.

ノート

This is a hosting integration, not an authentication client integration. It does not register application-side authentication services, create OIDC application registrations, or expose a Zitadel connection string. See Connect to Zitadel for the endpoint handoff and client configuration.

Prerequisites

• An Aspire AppHost. Follow Set up your environment if needed.
• A running container runtime for the Zitadel and PostgreSQL containers.
• The 📦 CommunityToolkit.Aspire.Hosting.Zitadel hosting package.
• The 📦 Aspire.Hosting.PostgreSQL hosting package for the database examples.

Run Zitadel locally

1. Install the hosting packages in your AppHost:

   Aspire CLI

   Aspire CLI — CommunityToolkit.Aspire.Hosting.Zitadel パッケージを追加

   aspire add zitadel

   Aspire CLI は対話的です。求められたら適切な結果を選択してください:

   Aspire CLI — 出力例

   Select an integration to add:
   
   > zitadel (CommunityToolkit.Aspire.Hosting.Zitadel)
   > Other results listed as selectable options...

   ノート

   結果が 1 つだけなら自動的に選択されます。バージョンは確認が必要です。
   apphost.cs (C# file-based app)

   C# — AppHost.cs

   #:package CommunityToolkit.Aspire.Hosting.Zitadel@*

   PackageReference (*.csproj)

   XML — CommunityToolkit.Aspire.Hosting.Zitadel パッケージ参照を追加

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

   Aspire CLI

   Aspire CLI — Aspire.Hosting.PostgreSQL パッケージを追加

   aspire add postgres

   Aspire CLI は対話的です。求められたら適切な結果を選択してください:

   Aspire CLI — 出力例

   Select an integration to add:
   
   > postgres (Aspire.Hosting.PostgreSQL)
   > Other results listed as selectable options...

   ノート

   結果が 1 つだけなら自動的に選択されます。バージョンは確認が必要です。
   apphost.cs (C# file-based app)

   C# — AppHost.cs

   #:package Aspire.Hosting.PostgreSQL@*

   PackageReference (*.csproj)

   XML — Aspire.Hosting.PostgreSQL パッケージ参照を追加

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

   For a TypeScript AppHost, installation generates the integration bindings in ./.aspire/modules/aspire.mjs.

2. Add PostgreSQL and attach it to Zitadel:

   TypeScript

   apphost.mts

   import { createBuilder } from './.aspire/modules/aspire.mjs';
   
   const builder = await createBuilder();
   
   const postgres = await builder.addPostgres('postgres');
   const zitadel = await builder.addZitadel('zitadel', { port: 8080 });
   await zitadel.withDatabase(postgres);
   
   await builder.build().run();

   C#

   AppHost.cs

   var builder = DistributedApplication.CreateBuilder(args);
   
   var postgres = builder.AddPostgres("postgres");
   var zitadel = builder.AddZitadel("zitadel", port: 8080)
       .WithDatabase(postgres);
   
   // After adding all resources, run the app...
   builder.Build().Run();

   The database helper adds a database named zitadel-db, supplies PostgreSQL settings to Zitadel, and adds a database reference and startup dependency. Port 8080 is the host port; the container also listens on port 8080.

3. Run the AppHost with aspire run. Wait for Zitadel to become healthy, then open the Zitadel Dashboard endpoint from the Aspire dashboard. Retrieve the initial credentials from the AppHost’s parameter values. The default username is admin, and the password is generated.

ヒント

Use a stable host port for local OIDC development. Configure clients with the actual endpoint URL shown by Aspire, including its scheme. Certificate configuration can change the endpoint to HTTPS even though its name remains http.

Next steps

• Set up the Zitadel hosting integration for database selection, secrets, external domains, persistence, and TLS behavior.
• Connect to Zitadel to pass an authority URL to an application and configure OpenID Connect.

See also

• Zitadel documentation
• PostgreSQL hosting integration
• Community Toolkit Zitadel source and README