Zitadel Implementation Status

Zitadel Implementation Status

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

Role Request Workflow

• Users submit role requests via POST /auth/role-requests
• Users view their requests via GET /auth/role-requests
• Admins list pending requests via GET /admin/role-requests
• Admins approve/reject via POST /admin/role-requests/{id}/approve|reject
• Approval triggers role grant in Zitadel via Management API
• Role revocation support (status: revoked)

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 defined in infrastructure/init-db.sql
• UUID primary keys via pgcrypto
• Repositories: RoleRequest, Application, ApiKey, PermissionRequest, CalendarPermission, 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

• Users submit permission requests via POST /auth/permission-requests
• Users view their own requests via GET /auth/permission-requests
• Admins manage permission requests via /admin/permission-requests (list, approve, reject, revoke)
• Admins manage OpenFGA tuples directly via /admin/permissions (list, grant, revoke, check)
• Supported object types: national_calendar, diocesan_calendar, wider_region, test_definition
• Supported relations: admin, viewer, editor, deleter
• PermissionRequestRepository with full CRUD operations backed by permission_requests table

OpenFGA Fine-Grained Authorization

• OpenFgaClient service (src/Services/OpenFgaClient.php) for communicating with the OpenFGA API
• OpenFgaAuthorizationMiddleware for fine-grained permission checks on /data/* and /tests routes
• HTTP method to relation mapping (PUT/PATCH → editor, DELETE → deleter)
• Path category to object type mapping (nation, diocese, widerregion, tests)
• Authorization model defined in infrastructure/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 and permission tables (infrastructure/init-db.sql)
• OpenFGA model initialization script (scripts/setup-openfga.sh)
• Production security documentation

Outstanding Work

API Backend

• #517 - Integrate fine-grained authorization with OpenFGA The OpenFGA client, middleware, and permission endpoints are implemented. Remaining work involves completing the integration and ensuring full coverage of authorization checks across all protected routes.