Zitadel RBAC Overview

The LiturgicalCalendar API uses Zitadel as its identity provider for OIDC-based authentication, role-based access control (RBAC), and user management. This replaces the earlier self-hosted JWT-only authentication (Phase 0) with an enterprise-grade identity platform.

Architecture

                    ┌─────────────────┐
                    │   PostgreSQL    │
                    │   Port: 5432    │
                    └───────┬─────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
     ┌────────────┐  ┌───────────┐  ┌──────────┐
     │  Zitadel   │  │  Login V2 │  │  litcal  │
     │  database  │  │  (shares  │  │ database │
     │  (managed) │  │  Zitadel  │  │  (RBAC)  │
     └────────────┘  │  network) │  └──────────┘
                     └───────────┘
              ┌─────────────┤
              │             │
              ▼             ▼
     ┌────────────┐  ┌───────────┐
     │  Zitadel   │  │  Login V2 │
     │  Port:8080 │  │  Port:8081│
     │  OIDC/API  │  │  Auth UI  │
     └──────┬─────┘  └───────────┘
            │
            ▼
  ┌───────────────────┐
  │ LiturgicalCalendar│
  │       API         │
  │   Port: 8000      │
  └───────────────────┘

Components

Service	Port	Purpose
Zitadel	8080	OIDC/OAuth2 identity provider, Console, Management API
Login V2	8081	Next.js authentication UI with passkeys and registration
PostgreSQL	5432	Shared database (Zitadel-managed + application RBAC)
API	8000	LiturgicalCalendar REST API

Middleware Pipeline

Protected routes pass through the following middleware chain:

1. ErrorHandlingMiddleware - Catches exceptions and formats error responses
2. LoggingMiddleware - Logs requests and responses
3. HttpsEnforcementMiddleware - Requires HTTPS in production (auth/admin routes)
4. OidcAvailabilityMiddleware - Returns 503 if Zitadel is not configured
5. OidcAuthMiddleware - Validates OIDC tokens, extracts user info and roles
6. AuthorizationMiddleware - Checks required roles and calendar-specific permissions

Roles

Four roles are defined in the Zitadel project:

Role	Purpose
admin	System administrator; bypasses all permission checks
developer	Register applications and generate API keys
calendar_editor	Contribute calendar data (with per-calendar permissions)
test_editor	Create and modify test definitions

Protected Routes

Authentication Endpoints (OIDC required)

Method	Route	Purpose
POST	/auth/role-requests	Submit a role request
GET	/auth/role-requests	View own role requests
GET	/auth/role-requests/status	Check role request status
POST	/auth/email-verification/resend	Resend verification email

Admin Endpoints (OIDC + admin role)

Method	Route	Purpose
GET	/admin/role-requests	List pending role requests
POST	/admin/role-requests/{id}/approve	Approve role request
POST	/admin/role-requests/{id}/reject	Reject role request
GET	/admin/notifications	Pending item counts
GET	/admin/users	List users with roles
DELETE	/admin/users/{userId}/roles/{role}	Revoke a user's role
GET	/admin/applications	List all applications
POST	/admin/applications/{uuid}/approve	Approve application
POST	/admin/applications/{uuid}/reject	Reject application
POST	/admin/applications/{uuid}/revoke	Revoke approved application

Developer Endpoints (OIDC + developer role)

Method	Route	Purpose
GET	/applications	List own applications
POST	/applications	Register new application
GET	/applications/{uuid}	Application details
PATCH	/applications/{uuid}	Update application
DELETE	/applications/{uuid}	Delete application
POST	/applications/{uuid}/resubmit	Resubmit rejected app
GET	/applications/{uuid}/keys	List API keys
POST	/applications/{uuid}/keys	Generate API key
DELETE	/applications/{uuid}/keys/{keyId}	Revoke API key
POST	/applications/{uuid}/keys/{keyId}/rotate	Rotate API key

Calendar Data Endpoints (OIDC + calendar_editor + per-calendar permission)

Method	Route	Purpose
PUT	/data/{category}/{calendar}	Create calendar definition
PATCH	/data/{category}/{calendar}	Update calendar definition
DELETE	/data/{category}/{calendar}	Delete calendar definition

Test Data Endpoints (OIDC + test_editor role)

Method	Route	Purpose
PUT	/tests	Create test definition
PATCH	/tests	Update test definition
DELETE	/tests	Delete test definition

Database Schema

The application database (litcal) stores RBAC data that complements Zitadel's identity management:

Table	Purpose
role_requests	User role assignment request workflow
user_calendar_permissions	Calendar-specific read/write permissions
permission_requests	Workflow for requesting calendar access
applications	Registered developer applications
api_keys	API keys with rate limiting, scope, and expiration
audit_log	Security and compliance audit trail

All tables use UUID primary keys via PostgreSQL's pgcrypto extension.

Key Source Files

File	Purpose
src/Services/ZitadelService.php	Zitadel Management API client
src/Http/Middleware/OidcAuthMiddleware.php	OIDC token validation and role extraction
src/Http/Middleware/OidcAvailabilityMiddleware.php	Checks if Zitadel is configured
src/Http/Middleware/AuthorizationMiddleware.php	Role and permission enforcement
src/Http/Middleware/ApiKeyMiddleware.php	API key extraction and validation
src/Repositories/	Database repositories for RBAC tables
src/Services/RateLimiter.php	IP-based rate limiting (login endpoint)

Implementation Status

See the Implementation Status page for details on what is complete and what remains to be done.

---

Authentication & RBAC: Zitadel Infrastructure Setup Next → | Home