Campaign_Tracker/_bmad-output/implementation-artifacts/1-4-keycloak-role-mapping-application-authorization.md

Story 1.4: Keycloak Role Mapping & Application Authorization

Status: ready-for-dev

Story

As a a developer, I want Keycloak roles mapped to application permission policies enforced on API routes and frontend features, so that each user sees only the capabilities appropriate to their operational role.

Acceptance Criteria

1. Given a Keycloak user has the ClientServices role When they authenticate and navigate Then they can access municipality profile and election-cycle creation routes and cannot access admin-only or production-only routes
2. Given a Keycloak user has the Admin role When they authenticate Then they can access all application routes including admin-sensitive functions
3. Given a user without a recognized application role authenticates When they access any protected route Then they receive 403 Forbidden and the unauthorized access attempt is logged with actor identity
4. Given a privileged operation is performed When it completes Then the authorization check result, actor, and resource are captured by the audit logging service within 5 seconds (NFR6, NFR7) And roles ClientServices, Production, Transportation, Support, and Admin are managed entirely in Keycloak Admin Console — FR27 is satisfied without a custom role management UI

Tasks / Subtasks

• Implement story behavior in aligned backend/frontend modules (AC: #1)
  • Add or update API/service/UI components required by the story scope
  • Keep legacy Access entities read-only and route writes to extension-layer structures
• Cover acceptance criteria #2 in implementation and tests (AC: #2)
  • Add validation/error handling and UX state updates as needed
• Cover acceptance criteria #3 in implementation and tests (AC: #3)
  • Add validation/error handling and UX state updates as needed
• Cover acceptance criteria #4 in implementation and tests (AC: #4)
  • Add validation/error handling and UX state updates as needed
• Validate and document completion evidence
  • Verify build/tests for touched modules
  • Capture changed files and any migration/config implications

Dev Notes

• Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables.
• Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations.
• Keep changes scoped to this story; do not pull forward Epic 2+ features.

Project Structure Notes

• Backend: BriansClientRouteReports.Server/
• Frontend: brians-client-route-reports-client/
• Story artifacts: _bmad-output/implementation-artifacts/

References

• Story source: _bmad-output/planning-artifacts/epics.md (Epic 1 / Story 1.4)
• Architecture constraints: _bmad-output/planning-artifacts/architecture.md
• UX patterns: _bmad-output/planning-artifacts/ux-design-specification.md

Dev Agent Record

Agent Model Used

GPT-5 Codex

Debug Log References

• Story generated from epic source and architecture/UX planning artifacts.

Completion Notes List

• Story context created and marked ready-for-dev.

File List

• _bmad-output/implementation-artifacts/1-4-keycloak-role-mapping-application-authorization.md