add RBAC documentation, update OpenAPI security, hide reviewed status from unauthenticated users

bakhterets · bakhterets · commit 5cbc7200b732 · 2026-02-17T17:11:51.000+01:00
diff --git a/docs/auth/rbac.md b/docs/auth/rbac.md
@@ -0,0 +1,110 @@
+# Role-Based Access Control (RBAC)
+
+## Overview
+
+The Status Dashboard implements RBAC for maintenance event management. Roles are extracted from the JWT `groups` claim and mapped to application permissions.
+
+## Roles
+
+Three roles are supported, with highest privilege taking precedence when a user has multiple roles:
+
+| Role | Priority | Description |
+|------|----------|-------------|
+| **sd_admins** | Highest | Full access to all operations |
+| **sd_operators** | Medium | Review and approve maintenance events |
+| **sd_creators** | Lowest | Create and manage own maintenance events |
+
+## Configuration
+
+Roles are mapped from IdP group names via environment variables:
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `SD_ADMINS_GROUP` | `admin-group` | IdP group for admin role |
+| `SD_OPERATORS_GROUP` | (none) | IdP group for operator role |
+| `SD_CREATORS_GROUP` | (none) | IdP group for creator role |
+
+## Permissions by Role
+
+### sd_admins
+
+- Unrestricted access to all maintenance operations
+- Bypass all status-based restrictions
+- Can transition events to any status
+- Events created with status `planned` (bypass review)
+
+### sd_operators
+
+- View all maintenance events regardless of status
+- Approve events: `pending_review` → `reviewed`
+- Create events with status `planned` (bypass review)
+- Cancel events in `pending_review` status
+- Update events in `pending_review` status
+
+### sd_creators
+
+- Create maintenance events (status: `pending_review`)
+- Modify **own** events only when status is `pending_review`
+- Cancel **own** events only when status is `pending_review`
+- Cannot modify events after approval (`reviewed`, `planned`, etc.)
+
+## Maintenance Status Workflow
+
+```
+Creator creates event
+        │
+        ▼
+  ┌─────────────┐
+  │pending_review│ ◄── sd_creators can modify/cancel here
+  └──────┬──────┘
+         │ Operator approves
+         ▼
+  ┌─────────────┐
+  │  reviewed   │
+  └──────┬──────┘
+         │ Checker auto-transitions
+         ▼
+  ┌─────────────┐
+  │   planned   │ ◄── sd_operators/sd_admins start here
+  └──────┬──────┘
+         │
+         ▼
+    [active → completed]
+```
+
+## Field Visibility
+
+Some fields are only visible to authenticated users:
+
+| Field | Visibility |
+|-------|------------|
+| `creator` | Authenticated only |
+| `contact_email` | Authenticated only |
+| `version` | Authenticated only |
+
+Events with status `pending_review` or `reviewed` are hidden from unauthenticated users.
+
+## Error Responses
+
+| HTTP Code | Condition |
+|-----------|-----------|
+| `401 Unauthorized` | Missing or invalid JWT token |
+| `403 Forbidden` | Insufficient role permissions |
+| `403 Forbidden` | Attempting to modify event you don't own (sd_creators) |
+| `403 Forbidden` | Attempting to modify event not in `pending_review` (sd_creators) |
+| `409 Conflict` | Version mismatch (concurrent modification) |
+| `409 Conflict` | Event no longer in expected status |
+
+## JWT Token Structure
+
+The API expects JWT tokens with the following claims:
+
+```json
+{
+  "preferred_username": "user@example.com",
+  "groups": ["sd_creators", "other-group"]
+}
+```
+
+- `preferred_username` → stored as event creator
+- `groups` → matched against configured role environment variables
diff --git a/docs/readme.md b/docs/readme.md
@@ -7,3 +7,4 @@
 - [Incident creation for API V2](./v2/v2_incident_creation.md)
 - [Components availability V2](./v2/v2_components_availability.md)
 - [Authentication for FE part](./auth/authentication.md)
+- [Role-Based Access Control (RBAC)](./auth/rbac.md)
diff --git a/internal/api/v2/v2.go b/internal/api/v2/v2.go
@@ -300,8 +300,9 @@ func GetIncidentHandler(dbInst *db.DB, logger *zap.Logger, svc *rbac.Service) gi
 		}
 
 		isAuth := hasExtendedView(c, svc)
-		// Hide pending review maintenance from non-authenticated users
-		if !isAuth && r.Type == event.TypeMaintenance && r.Status == event.MaintenancePendingReview {
+		// Hide pending review and reviewed maintenance from non-authenticated users
+		if !isAuth && r.Type == event.TypeMaintenance &&
+			(r.Status == event.MaintenancePendingReview || r.Status == event.MaintenanceReviewed) {
 			apiErrors.RaiseStatusNotFoundErr(c, apiErrors.ErrIncidentDSNotExist)
 			return
 		}
diff --git a/internal/db/db.go b/internal/db/db.go
@@ -124,8 +124,8 @@ func applyEventsFilters(base *gorm.DB, params *IncidentsParams, isAuth bool) (*g
 
 	if !isAuth {
 		base = base.Where(
-			"NOT (incident.type = ? AND incident.status = ?)",
-			event.TypeMaintenance, event.MaintenancePendingReview,
+			"NOT (incident.type = ? AND incident.status IN (?, ?))",
+			event.TypeMaintenance, event.MaintenancePendingReview, event.MaintenanceReviewed,
 		)
 	}
 
diff --git a/openapi.yaml b/openapi.yaml
@@ -12,7 +12,7 @@ info:
     - `contact_email` - Contact email for maintenance events
     - `version` - Version number for optimistic locking (conflict detection)
     
-    Maintenance events with status `pending_review` are only visible to authenticated users.
+    Maintenance events with status `pending_review` or `reviewed` are only visible to authenticated users.
     
     ## Optimistic Locking
     
@@ -21,6 +21,25 @@ info:
     - PATCH requests must include the current `version` number
     - If the version doesn't match (event was modified by another user), a 409 Conflict is returned
     - On successful update, the version is automatically incremented
+    
+    ## Role-Based Access Control (RBAC)
+    
+    The API implements RBAC with three roles (highest to lowest privilege):
+    
+    | Role | Permissions |
+    |------|-------------|
+    | **sd_admins** | Unrestricted access to all operations, bypass status restrictions |
+    | **sd_operators** | View all events, approve pending_review → reviewed, create events (status: planned) |
+    | **sd_creators** | Create maintenance (status: pending_review), modify/cancel own pending_review events |
+    
+    Roles are determined from the JWT `groups` claim and mapped via environment variables:
+    - `SD_ADMINS_GROUP` (default: "admin-group")
+    - `SD_OPERATORS_GROUP`
+    - `SD_CREATORS_GROUP`
+    
+    ### Error Responses
+    - `401 Unauthorized` - Missing or invalid JWT token
+    - `403 Forbidden` - Insufficient role permissions or not event owner
 servers:
   - url: http://localhost:8000
 tags:
@@ -34,6 +53,8 @@ tags:
     description: Operations about components
   - name: v1
     description: Deprecated API schema for backward compatibility
+security:
+  - BearerAuth: []
 paths:
   /auth/login:
     get:
@@ -331,6 +352,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/IncidentPostResponse'
+        '401':
+          description: Unauthorized - missing or invalid JWT token
+        '403':
+          description: Forbidden - insufficient permissions for this operation
 
   /v2/events/{event_id}:
     get:
@@ -386,6 +411,10 @@ paths:
           description: Invalid ID supplied
         '404':
           description: Event not found.
+        '401':
+          description: Unauthorized - missing or invalid JWT token
+        '403':
+          description: Forbidden - insufficient permissions or not event owner
         '409':
           description: Version conflict - event has been modified by another user. Fetch the latest version and retry.
           content:
@@ -519,6 +548,10 @@ paths:
           description: Invalid ID supplied
         '404':
           description: Incident not found.
+        '401':
+          description: Unauthorized - missing or invalid JWT token
+        '403':
+          description: Forbidden - insufficient permissions or not event owner
         '409':
           description: Version conflict - incident has been modified by another user. Fetch the latest version and retry.
           content:
@@ -1214,3 +1247,9 @@ components:
       schema:
         type: integer
         example: 0
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token from Keycloak. Include in Authorization header as "Bearer <token>"
diff --git a/specs/001-maintenance-rbac/spec.md b/specs/001-maintenance-rbac/spec.md
@@ -168,7 +168,7 @@ The system enforces role-based permissions throughout the maintenance lifecycle.
 #### Status Workflow
 
 - **FR-022**: System MUST support the following status flow for sd_creators: pending review → reviewed → planned → [existing statuses]
-- **FR-022-1**: System MUST NOT include maintenance events with "pending review" status in API responses for unauthenticated users
+- **FR-022-1**: System MUST NOT include maintenance events with "pending review" or "reviewed" status in API responses for unauthenticated users
 - **FR-022a**: System MUST support direct "planned" status for events created by sd_operators and sd_admins users (bypassing pending review and reviewed statuses)
 - **FR-022b**: System MUST support "cancelled" as a terminal status reachable from any other status, representing event removal/cancellation
 - **FR-023**: The internal checker goroutine in the existing "checker" module MUST automatically change status from "reviewed" to "planned" without performing additional validation

Original file line number	Diff line number	Diff line change
`@@ -300,8 +300,9 @@ func GetIncidentHandler(dbInst db.DB, logger zap.Logger, svc *rbac.Service) gi`
`300`	`300`	`}`
`301`	`301`
`302`	`302`	`isAuth := hasExtendedView(c, svc)`
`303`		`- // Hide pending review maintenance from non-authenticated users`
`304`		`- if !isAuth && r.Type == event.TypeMaintenance && r.Status == event.MaintenancePendingReview {`
	`303`	`+ // Hide pending review and reviewed maintenance from non-authenticated users`
	`304`	`+ if !isAuth && r.Type == event.TypeMaintenance &&`
	`305`	`+ (r.Status == event.MaintenancePendingReview \|\| r.Status == event.MaintenanceReviewed) {`
`305`	`306`	`apiErrors.RaiseStatusNotFoundErr(c, apiErrors.ErrIncidentDSNotExist)`
`306`	`307`	`return`
`307`	`308`	`}`
Original file line number	Diff line number	Diff line change
`@@ -124,8 +124,8 @@ func applyEventsFilters(base gorm.DB, params IncidentsParams, isAuth bool) (*g`
`124`	`124`
`125`	`125`	`if !isAuth {`
`126`	`126`	`base = base.Where(`
`127`		`- "NOT (incident.type = ? AND incident.status = ?)",`
`128`		`- event.TypeMaintenance, event.MaintenancePendingReview,`
	`127`	`+ "NOT (incident.type = ? AND incident.status IN (?, ?))",`
	`128`	`+ event.TypeMaintenance, event.MaintenancePendingReview, event.MaintenanceReviewed,`
`129`	`129`	`)`
`130`	`130`	`}`
`131`	`131`