---

name: zitadel-identity description: | Zitadel identity provider setup, configuration, and OIDC integration. Use when: (1) Setting up Zitadel as OIDC/OAuth2 identity provider (2) Configuring Zitadel with Caddy reverse proxy (3) Creating OAuth2/OIDC applications for services (4) Managing users, organizations, and service accounts (5) Integrating applications with Zitadel SSO (Nextcloud, Windmill, etc.) (6) Troubleshooting authentication, token, or connectivity issues (7) Using Zitadel APIs for automation

Zitadel Identity Provider

Zitadel is a modern identity management platform providing OIDC, OAuth2, and SAML authentication. This skill covers Docker deployment with Caddy reverse proxy.

Quick Reference

Architecture

CopyInternet → Caddy (80/443) → Zitadel API (h2c://zitadel:8080)
                          → Login UI (http://zitadel-login:3000)

PostgreSQL ← zitadel-init (runs once)
           ← zitadel (API server)

Three containers:

• zitadel-init - Database initialization (runs once, exits)
• zitadel - API server (gRPC/REST on port 8080)
• zitadel-login - Login UI (port 3000)

Essential Environment Variables

Copy# Required
ZITADEL_MASTERKEY=<32-char-random-string>
ZITADEL_DATABASE_POSTGRES_HOST=postgres
ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=<password>
ZITADEL_EXTERNALDOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true
ZITADEL_TLS_ENABLED=false  # Caddy handles TLS

Generate masterkey: tr -dc A-Za-z0-9 </dev/urandom | head -c 32

Caddy Configuration

Critical: Use h2c:// for HTTP/2 cleartext (required for gRPC):

Copyauth.example.com {
    handle /ui/v2/login/* {
        reverse_proxy http://zitadel-login:3000
    }
    handle {
        reverse_proxy h2c://zitadel:8080
    }
}

Deployment Steps

1. Start PostgreSQL:

   Copydocker compose up -d postgres
   

2. Initialize database:

   Copydocker compose run zitadel-init
   

3. Start services:

   Copydocker compose up -d zitadel zitadel-login caddy
   

4. Verify health:

   Copycurl https://auth.example.com/healthz
   

5. Access console:

   Copyhttps://auth.example.com/ui/console
   

Creating OIDC Applications

1. Console → Organization → Projects → Applications → + New
2. Select application type (Web, Native, API)
3. Configure redirect URIs
4. Save and copy Client ID and Client Secret

Common redirect URIs:

• Nextcloud: https://files.example.com/apps/user_oidc/code
• Windmill: https://windmill.example.com/user/login_callback/zitadel

Service Users (API Access)

1. Console → Users → Service Users → + New
2. Create Personal Access Token (PAT)
3. Assign roles (Org Owner, Project Owner)
4. Use in API calls:

   Copycurl -H "Authorization: Bearer <PAT>" \
     https://auth.example.com/management/v1/orgs/me
   

Reference Files

Official Documentation

Troubleshooting Quick Guide