Zitadel Implementation Status - Liturgical-Calendar/LiturgicalCalendarAPI GitHub Wiki

This page tracks what has been implemented and what remains to be done for the Zitadel RBAC integration.

Completed

Authentication & OIDC

  • OIDC token validation via JWKS with per-issuer keyset caching (OidcAuthMiddleware)
  • Support for both HttpOnly cookie and Authorization: Bearer header authentication
  • Role extraction from Zitadel token claims (urn:zitadel:iam:org:project:roles)
  • OIDC availability checking with 503 fallback (OidcAvailabilityMiddleware)
  • HTTPS enforcement for auth endpoints in staging/production
  • Legacy JWT authentication preserved as fallback (JwtAuthMiddleware)

Zitadel Management API

  • Full client for user management (list, search, fetch by ID) (ZitadelService)
  • Role management (grant, revoke, check, update grants)
  • Intelligent single-role revocation (preserves other roles on same grant)
  • OIDC discovery document caching (1-hour TTL)
  • Factory method for environment-based instantiation

Access Request Workflow

  • Users submit unified access requests (role + resource permissions) via POST /auth/access-requests
  • Users view their requests via GET /auth/access-requests
  • Admins list pending requests via GET /admin/access-requests
  • Admins approve/reject/revoke via POST /admin/access-requests/{id}/approve|reject|revoke
  • Approval triggers the role grant in Zitadel and writes permission tuples to OpenFGA via the outbox
  • Role revocation cascades: all of the user's OpenFGA tuples are removed

Application & API Key Management

  • Developers register applications with name, description, website
  • Application approval workflow (pending → approved/rejected/revoked)
  • Resubmission of rejected applications
  • API key generation from approved applications (with requested scope)
  • API key rotation and revocation
  • Key prefix tracking for identification
  • Scope control (read/write)
  • Expiration support

Admin Features

  • List and manage users with roles
  • Revoke individual user roles
  • Approve/reject/revoke applications
  • Notification counts (pending role requests + pending applications)
  • Email verification resend

Database & Repositories

  • PostgreSQL schema managed via Doctrine migrations (src/Migrations/), bootstrap in scripts/init-db.sql
  • UUID primary keys via pgcrypto
  • Repositories: AccessRequest, Application, ApiKey, Outbox, UserNotification, AuditLog
  • Audit logging of all administrative actions with IP and user agent

Security

  • IP-based rate limiting on login endpoint
  • Argon2id password hashing
  • JWT placeholder detection in staging/production
  • CORS origin validation
  • HttpOnly cookie support with SameSite attributes

API Key Middleware & Rate Limiting

  • ApiKeyMiddleware wired into Router middleware pipeline (#515)
  • API key rate limiting enforcement (#516)

Calendar-Specific Permissions

  • Resource permissions are requested together with roles via the unified /auth/access-requests workflow
  • Admins manage OpenFGA tuples directly via /admin/permissions (list, grant, revoke, check)
  • Supported object types: national_calendar, diocesan_calendar, wider_region, general_roman_calendar, national_calendar_test, diocesan_calendar_test, general_roman_calendar_test
  • Supported relations: admin, editor, viewer (superset chain: admin ⊇ editor ⊇ viewer)
  • AccessRequestRepository with full CRUD operations backed by the access_requests table

OpenFGA Fine-Grained Authorization

See OpenFGA Fine-Grained Authorization for full documentation.

  • OpenFgaClient service (src/Services/OpenFgaClient.php) for communicating with the OpenFGA API
  • OpenFgaAuthorizationMiddleware for fine-grained permission checks on /data/*, /tests, /temporale, /decrees, and /missals routes
  • HTTP method to relation mapping (PUT/DELETE → admin, PATCH → editor; test creation → editor)
  • Path category to object type mapping (nation, diocese, widerregion) and calendar-scoped test resolution via TestScopeResolver
  • Wider-region governance inherited from member nations (member_nation tuple-to-userset)
  • Transactional outbox (openfga_outbox) with sync fast path, Redis Streams consumer, and cron backstop
  • Authorization model defined in scripts/openfga-model.json
  • Conditionally applied in the middleware pipeline when OpenFGA is configured
  • Admin role bypass (consistent with role-based authorization)

Frontend

  • Zitadel OIDC login flow with Authorization Code Flow and PKCE (#280)
  • Role request management UI (#278)
  • Application management dashboard for developers (#279)
  • Admin user management UI with role revocation and notification badges (#281)
  • Centralized admin interfaces (#197)

Infrastructure

  • Docker Compose setup (Zitadel, Login V2, OpenFGA, PostgreSQL, Adminer)
  • Database initialization script with RBAC tables (scripts/init-db.sql)
  • OpenFGA model initialization script (scripts/setup-openfga.sh)
  • Production security documentation

Outstanding Work

API Backend

Authentication & RBAC: ← [Zitadel Production Security]] ](/Liturgical-Calendar/LiturgicalCalendarAPI/wiki/[[Home)