Zeeget.Zitadel.AspNetCore 0.19.1

ZZitadel

A Zitadel-first .NET library for Zeeget SaaS applications. It makes Zitadel integration straightforward for .NET projects: authenticating users, resolving the current user and organization/tenant, reading roles and memberships, and bootstrapping organization access.

This library is intentionally coupled to Zitadel. It does not provide a generic identity abstraction, and you should not expect to swap Zitadel out behind it.

Status: 0.4.0. The functional core is complete — authentication, provisioning (register, invite, resend invitation, grant/revoke, org-scoped removal, and social sign-up that creates a tenant), organization rename, role resolution with an optional Management-API fallback, listing the current user's organizations from claims, readiness health checks, and an observability seam — covered by unit tests, real-Zitadel integration tests, and a headless browser e2e for the social flow. Pre-1.0: the public API is not yet stable and minor releases may include breaking changes (see the changelog).

Packages

Zeeget.Zitadel.AspNetCore depends on Zeeget.Zitadel.Core; never the reverse. The library owns no datastore — resilience comes from idempotent check-then-act against Zitadel.

Getting started

dotnet add package Zeeget.Zitadel.AspNetCore   # also pulls in Zeeget.Zitadel.Core

Wire inbound authentication (validates Zitadel JWTs locally against the issuer's JWKS) and the claims accessors:

builder.Services.AddZitadelAuthentication(builder.Configuration); // binds the "Zitadel" section

Wire provisioning (registration, invitations, role grant/revoke, org-scoped removal) — calls Zitadel's Management API as a service identity:

builder.Services.AddZitadelProvisioning(builder.Configuration);

Configuration (the Zitadel section — supply secrets from your secret store, never in code):

{
  "Zitadel": {
    "Authority": "https://your-instance.zitadel.cloud",
    "Audience": "<project or app id expected in the token's aud>",
    "ServiceUserKey": "<JWT-profile key JSON for the management service identity>",
    "ProjectId": "<id of the project whose roles you grant>"
  }
}

See docs/setup/zitadel.md for the Zitadel-side setup (app token type = JWT, service user/key, scopes/claims). For a full runnable example, follow the sample walkthrough.

Capabilities

• Authenticate users against Zitadel via standard OIDC / JWT bearer (local JWKS validation).
• Register a user (manual or social sign-up) and, in one flow, create their organization (tenant) and make them its owner.
• Invite other users into an organization with an application role.
• Resolve the current user and current organization (tenant), and the user's roles within an organization, from the request's token claims.
• Grant / revoke application roles by key, and read a user's membership and roles in an organization via the Management API (the role taxonomy is the consuming app's; the library only knows the native organization owner).
• Remove a user from an organization (org-scoped and multi-org-safe).

A Zitadel Organization is the application tenant, and a user may belong to one or more organizations. See docs/architecture/zitadel-model.md.

How it talks to Zitadel (hybrid)

• Authentication uses standard ASP.NET Core OIDC / JWT bearer against Zitadel.
• Management (organizations, users, memberships, roles) calls Zitadel's Management & Auth APIs directly over REST. No mandatory third-party Zitadel SDK.

Observability

The library is instrumented with OpenTelemetry-compatible traces and metrics plus structured ILogger logs (ADR-0021). It ships no exporter and forces no backend — you own export. Subscribe by name via the public constants on ZitadelDiagnostics:

using Zeeget.Zitadel.Core.Diagnostics;

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(ZitadelDiagnostics.ActivitySourceName).AddOtlpExporter())
    .WithMetrics(m => m.AddMeter(ZitadelDiagnostics.MeterName).AddOtlpExporter());

What it emits:

• Traces — one span per provisioning operation (register, invite, grant_role, revoke_role, remove_from_organization), tagged with the outcome and the opaque Zitadel ids it acted on.
• Metrics — a zitadel.provisioning.operations counter and a zitadel.provisioning.operation.duration histogram, tagged low-cardinality by operation and outcome (plus error.type on failures). HTTP-level retry/circuit metrics come from the resilient HttpClient pipeline's own built-in telemetry.
• No secrets or PII ever reach a metric tag, span tag, or log — opaque ids appear on spans only, never on metric tags.

Swap AddOtlpExporter() for AddConsoleExporter() or any other exporter — the library is exporter-agnostic.

Requirements

• .NET 10 (LTS) or later.
• A reachable Zitadel instance (issuer + a service identity for management calls).

Documentation

• Architecture: decisions · boundaries · Zitadel model
• Workflows: development · testing · release
• Setup: Zitadel instance/app configuration · user onboarding (registration, invitation, landing) · securing access (Console restricted to admins).
• Sample: a runnable minimal-API wiring walkthrough.
• Observability: wiring OpenTelemetry export.
• Contributors and AI agents: start with CLAUDE.md / AGENTS.md.

License

MIT © Zeeget. See LICENSE.