bakery-admin/bakery-ia

Fork 0

Files

Urtzi Alfaro 667e6e0404 New alert service

2025-12-05 20:07:01 +01:00

19 KiB

Raw Blame History

Role-Based Access Control (RBAC) Implementation Guide

Last Updated: November 2025 Status: Implementation in Progress Platform: Bakery-IA Microservices

Overview
Role System Architecture
Access Control Implementation
Service-by-Service RBAC Matrix
Implementation Guidelines
Testing Strategy
Related Documentation

Overview

This guide provides comprehensive information about implementing Role-Based Access Control (RBAC) across the Bakery-IA platform, consisting of 15 microservices with 250+ API endpoints.

Key Components

4 User Roles: Viewer → Member → Admin → Owner (hierarchical)
3 Subscription Tiers: Starter → Professional → Enterprise
250+ API Endpoints: Requiring granular access control
Tenant Isolation: All services enforce tenant-level data isolation

Implementation Status

Implemented:

✅ JWT authentication across all services
✅ Tenant isolation via path parameters
✅ Basic admin role checks in auth service
✅ Subscription tier checking framework

In Progress:

🔧 Role decorators on service endpoints
🔧 Subscription tier enforcement on premium features
🔧 Fine-grained resource permissions
🔧 Audit logging for sensitive operations

Role System Architecture

User Role Hierarchy

Defined in shared/auth/access_control.py:

class UserRole(Enum):
    VIEWER = "viewer"    # Read-only access
    MEMBER = "member"    # Read + basic write operations
    ADMIN = "admin"      # Full operational access
    OWNER = "owner"      # Full control including tenant settings

ROLE_HIERARCHY = {
    UserRole.VIEWER: 1,
    UserRole.MEMBER: 2,
    UserRole.ADMIN: 3,
    UserRole.OWNER: 4,
}

Permission Matrix by Action

Action Type	Viewer	Member	Admin	Owner
Read data	✓	✓	✓	✓
Create records	✗	✓	✓	✓
Update records	✗	✓	✓	✓
Delete records	✗	✗	✓	✓
Manage users	✗	✗	✓	✓
Configure settings	✗	✗	✓	✓
Billing/subscription	✗	✗	✗	✓
Delete tenant	✗	✗	✗	✓

Subscription Tier System

class SubscriptionTier(Enum):
    STARTER = "starter"           # Basic features
    PROFESSIONAL = "professional" # Advanced analytics & ML
    ENTERPRISE = "enterprise"     # Full feature set + priority support

TIER_HIERARCHY = {
    SubscriptionTier.STARTER: 1,
    SubscriptionTier.PROFESSIONAL: 2,
    SubscriptionTier.ENTERPRISE: 3,
}

Tier Features Matrix

Feature	Starter	Professional	Enterprise
Basic Inventory	✓	✓	✓
Basic Sales	✓	✓	✓
Basic Recipes	✓	✓	✓
ML Forecasting	✓ (7-day)	✓ (30+ day)	✓ (unlimited)
Model Training	✓ (1/day, 1k rows)	✓ (5/day, 10k rows)	✓ (unlimited)
Advanced Analytics	✗	✓	✓
Custom Reports	✗	✓	✓
Production Optimization	✓ (basic)	✓ (advanced)	✓ (AI-powered)
Historical Data	7 days	90 days	Unlimited
Multi-location	1	2	Unlimited
API Access	✗	✗	✓
Priority Support	✗	✗	✓
Max Users	5	20	Unlimited
Max Products	50	500	Unlimited

Access Control Implementation

Available Decorators

The platform provides these decorators in shared/auth/access_control.py:

Subscription Tier Enforcement

# Require specific subscription tier(s)
@require_subscription_tier(['professional', 'enterprise'])
async def advanced_analytics(...):
    pass

# Convenience decorators
@enterprise_tier_required
async def enterprise_feature(...):
    pass

@analytics_tier_required  # Requires professional or enterprise
async def analytics_endpoint(...):
    pass

Role-Based Enforcement

# Require specific role(s)
@require_user_role(['admin', 'owner'])
async def delete_resource(...):
    pass

# Convenience decorators
@admin_role_required
async def admin_only(...):
    pass

@owner_role_required
async def owner_only(...):
    pass

Combined Enforcement

# Require both tier and role
@require_tier_and_role(['professional', 'enterprise'], ['admin', 'owner'])
async def premium_admin_feature(...):
    pass

FastAPI Dependencies

Available in shared/auth/tenant_access.py:

from fastapi import Depends
from shared.auth.tenant_access import (
    get_current_user_dep,
    verify_tenant_access_dep,
    verify_tenant_permission_dep
)

# Basic authentication
@router.get("/{tenant_id}/resource")
async def get_resource(
    tenant_id: str,
    current_user: Dict = Depends(get_current_user_dep)
):
    pass

# Tenant access verification
@router.get("/{tenant_id}/resource")
async def get_resource(
    tenant_id: str = Depends(verify_tenant_access_dep)
):
    pass

# Resource permission check
@router.delete("/{tenant_id}/resource/{id}")
async def delete_resource(
    tenant_id: str = Depends(verify_tenant_permission_dep("resource", "delete"))
):
    pass

Service-by-Service RBAC Matrix

Authentication Service

Critical Operations:

User deletion requires Admin role + audit logging
Password changes should enforce strong password policy
Email verification prevents account takeover

Endpoint	Method	Min Role	Min Tier	Notes
`/register`	POST	Public	Any	Rate limited
`/login`	POST	Public	Any	Rate limited (3-5 attempts)
`/delete/{user_id}`	DELETE	Admin	Any	🔴 CRITICAL - Audit logged
`/change-password`	POST	Authenticated	Any	Own account only
`/profile`	GET/PUT	Authenticated	Any	Own account only

Recommendations:

✅ IMPLEMENTED: Admin role check on deletion
🔧 ADD: Rate limiting on login/register
🔧 ADD: Audit log for user deletion
🔧 ADD: MFA for admin accounts
🔧 ADD: Password strength validation

Tenant Service

Critical Operations:

Tenant deletion/deactivation (Owner only)
Subscription changes (Owner only)
Role modifications (Admin+, prevent owner changes)
Member removal (Admin+)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}`	GET	Viewer	Any	Tenant member
`/{tenant_id}`	PUT	Admin	Any	Admin+ only
`/{tenant_id}/deactivate`	POST	Owner	Any	🔴 CRITICAL - Owner only
`/{tenant_id}/members`	GET	Viewer	Any	View team
`/{tenant_id}/members`	POST	Admin	Any	Invite users
`/{tenant_id}/members/{user_id}/role`	PUT	Admin	Any	Change roles
`/{tenant_id}/members/{user_id}`	DELETE	Admin	Any	🔴 Remove member
`/subscriptions/{tenant_id}/upgrade`	POST	Owner	Any	🔴 CRITICAL
`/subscriptions/{tenant_id}/cancel`	POST	Owner	Any	🔴 CRITICAL

Recommendations:

✅ IMPLEMENTED: Role checks for member management
🔧 ADD: Prevent removing the last owner
🔧 ADD: Prevent owner from changing their own role
🔧 ADD: Subscription change confirmation
🔧 ADD: Audit log for all tenant modifications

Sales Service

Critical Operations:

Sales record deletion (affects financial reports)
Product deletion (affects historical data)
Bulk imports (data integrity)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/sales`	GET	Viewer	Any	Read sales data
`/{tenant_id}/sales`	POST	Member	Any	Create sales
`/{tenant_id}/sales/{id}`	DELETE	Admin	Any	🔴 Affects reports
`/{tenant_id}/products/{id}`	DELETE	Admin	Any	🔴 Affects history
`/{tenant_id}/analytics/*`	GET	Viewer	Professional	💰 Premium

Recommendations:

🔧 ADD: Soft delete for sales records (audit trail)
🔧 ADD: Subscription tier check on analytics endpoints
🔧 ADD: Prevent deletion of products with sales history

Inventory Service

Critical Operations:

Ingredient deletion (affects recipes)
Manual stock adjustments (inventory manipulation)
Compliance record deletion (regulatory violation)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/ingredients`	GET	Viewer	Any	List ingredients
`/{tenant_id}/ingredients/{id}`	DELETE	Admin	Any	🔴 Affects recipes
`/{tenant_id}/stock/adjustments`	POST	Admin	Any	🔴 Manual adjustment
`/{tenant_id}/analytics/*`	GET	Viewer	Professional	💰 Premium
`/{tenant_id}/reports/cost-analysis`	GET	Admin	Professional	💰 Sensitive

Recommendations:

🔧 ADD: Prevent deletion of ingredients used in recipes
🔧 ADD: Audit log for all stock adjustments
🔧 ADD: Compliance records cannot be deleted
🔧 ADD: Role check: only Admin+ can see cost data

Production Service

Critical Operations:

Batch deletion (affects inventory and tracking)
Schedule changes (affects production timeline)
Quality check modifications (compliance)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/batches`	GET	Viewer	Any	View batches
`/{tenant_id}/batches/{id}`	DELETE	Admin	Any	🔴 Affects tracking
`/{tenant_id}/schedules/{id}`	PUT	Admin	Any	Schedule changes
`/{tenant_id}/capacity/optimize`	POST	Admin	Any	Basic optimization
`/{tenant_id}/efficiency-trends`	GET	Viewer	Professional	💰 Historical trends
`/{tenant_id}/capacity-analysis`	GET	Admin	Professional	💰 Advanced analysis

Tier-Based Features:

Starter: Basic capacity, 7-day history, simple optimization
Professional: Advanced metrics, 90-day history, advanced algorithms
Enterprise: Predictive maintenance, unlimited history, AI-powered

Recommendations:

🔧 ADD: Optimization depth limits per tier
🔧 ADD: Historical data limits (7/90/unlimited days)
🔧 ADD: Prevent deletion of completed batches

Forecasting Service

Critical Operations:

Forecast generation (consumes ML resources)
Bulk operations (resource intensive)
Scenario creation (computational cost)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/forecasts`	GET	Viewer	Any	View forecasts
`/{tenant_id}/forecasts/generate`	POST	Admin	Any	Trigger ML forecast
`/{tenant_id}/scenarios`	GET	Viewer	Enterprise	💰 Scenario modeling
`/{tenant_id}/scenarios`	POST	Admin	Enterprise	💰 Create scenario
`/{tenant_id}/analytics/accuracy`	GET	Viewer	Professional	💰 Model metrics

Tier-Based Limits:

Starter: 7-day forecasts, 10/day quota
Professional: 30+ day forecasts, 100/day quota, accuracy metrics
Enterprise: Unlimited forecasts, scenario modeling, custom parameters

Recommendations:

🔧 ADD: Forecast horizon limits per tier
🔧 ADD: Rate limiting based on tier (ML cost)
🔧 ADD: Quota limits per subscription tier
🔧 ADD: Scenario modeling only for Enterprise

Training Service

Critical Operations:

Model training (expensive ML operations)
Model deployment (affects production forecasts)
Model retraining (overwrites existing models)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/training-jobs`	POST	Admin	Any	Start training
`/{tenant_id}/training-jobs/{id}/cancel`	POST	Admin	Any	Cancel training
`/{tenant_id}/models/{id}/deploy`	POST	Admin	Any	🔴 Deploy model
`/{tenant_id}/models/{id}/artifacts`	GET	Admin	Enterprise	💰 Download artifacts
`/ws/{tenant_id}/training`	WebSocket	Admin	Any	Real-time updates

Tier-Based Quotas:

Starter: 1 training job/day, 1k rows max, simple Prophet
Professional: 5 jobs/day, 10k rows max, model versioning
Enterprise: Unlimited jobs, unlimited rows, custom parameters

Recommendations:

🔧 ADD: Training quota per subscription tier
🔧 ADD: Dataset size limits per tier
🔧 ADD: Queue priority based on subscription
🔧 ADD: Artifact download only for Enterprise

Orders Service

Critical Operations:

Order cancellation (affects production and customer)
Customer deletion (GDPR compliance required)
Procurement scheduling (affects inventory)

Endpoint	Method	Min Role	Min Tier	Notes
`/{tenant_id}/orders`	GET	Viewer	Any	View orders
`/{tenant_id}/orders/{id}/cancel`	POST	Admin	Any	🔴 Cancel order
`/{tenant_id}/customers/{id}`	DELETE	Admin	Any	🔴 GDPR compliance
`/{tenant_id}/procurement/requirements`	GET	Admin	Professional	💰 Planning
`/{tenant_id}/procurement/schedule`	POST	Admin	Professional	💰 Scheduling

Recommendations:

🔧 ADD: Order cancellation requires reason/notes
🔧 ADD: Customer deletion with GDPR-compliant export
🔧 ADD: Soft delete for orders (audit trail)

Implementation Guidelines

Step 1: Add Role Decorators

from shared.auth.access_control import require_user_role

@router.delete("/{tenant_id}/sales/{sale_id}")
@require_user_role(['admin', 'owner'])
async def delete_sale(
    tenant_id: str,
    sale_id: str,
    current_user: Dict = Depends(get_current_user_dep)
):
    # Existing logic...
    pass

Step 2: Add Subscription Tier Checks

from shared.auth.access_control import require_subscription_tier

@router.post("/{tenant_id}/forecasts/generate")
@require_user_role(['admin', 'owner'])
async def generate_forecast(
    tenant_id: str,
    horizon_days: int,
    current_user: Dict = Depends(get_current_user_dep)
):
    # Check tier-based limits
    tier = current_user.get('subscription_tier', 'starter')
    max_horizon = {
        'starter': 7,
        'professional': 90,
        'enterprise': 365
    }

    if horizon_days > max_horizon.get(tier, 7):
        raise HTTPException(
            status_code=402,
            detail=f"Forecast horizon limited to {max_horizon[tier]} days for {tier} tier"
        )

    # Check daily quota
    daily_quota = {'starter': 10, 'professional': 100, 'enterprise': None}
    if not await check_quota(tenant_id, 'forecasts', daily_quota[tier]):
        raise HTTPException(
            status_code=429,
            detail=f"Daily forecast quota exceeded for {tier} tier"
        )

    # Existing logic...

Step 3: Add Audit Logging

from shared.audit import log_audit_event

@router.delete("/{tenant_id}/customers/{customer_id}")
@require_user_role(['admin', 'owner'])
async def delete_customer(
    tenant_id: str,
    customer_id: str,
    current_user: Dict = Depends(get_current_user_dep)
):
    # Existing deletion logic...

    # Add audit log
    await log_audit_event(
        tenant_id=tenant_id,
        user_id=current_user["user_id"],
        action="customer.delete",
        resource_type="customer",
        resource_id=customer_id,
        severity="high"
    )

Step 4: Implement Rate Limiting

from shared.rate_limit import check_quota

@router.post("/{tenant_id}/training-jobs")
@require_user_role(['admin', 'owner'])
async def create_training_job(
    tenant_id: str,
    dataset_rows: int,
    current_user: Dict = Depends(get_current_user_dep)
):
    tier = current_user.get('subscription_tier', 'starter')

    # Check daily quota
    daily_limits = {'starter': 1, 'professional': 5, 'enterprise': None}
    if not await check_quota(tenant_id, 'training_jobs', daily_limits[tier], period=86400):
        raise HTTPException(
            status_code=429,
            detail=f"Daily training job limit reached for {tier} tier ({daily_limits[tier]}/day)"
        )

    # Check dataset size limit
    dataset_limits = {'starter': 1000, 'professional': 10000, 'enterprise': None}
    if dataset_limits[tier] and dataset_rows > dataset_limits[tier]:
        raise HTTPException(
            status_code=402,
            detail=f"Dataset size limited to {dataset_limits[tier]} rows for {tier} tier"
        )

    # Existing logic...

Testing Strategy

Unit Tests

# Test role enforcement
def test_delete_requires_admin_role():
    response = client.delete(
        "/api/v1/tenant123/sales/sale456",
        headers={"Authorization": f"Bearer {member_token}"}
    )
    assert response.status_code == 403
    assert "insufficient_permissions" in response.json()["detail"]["error"]

# Test subscription tier enforcement
def test_forecasting_horizon_limit_starter():
    response = client.post(
        "/api/v1/tenant123/forecasts/generate",
        json={"horizon_days": 30},  # Exceeds 7-day limit
        headers={"Authorization": f"Bearer {starter_user_token}"}
    )
    assert response.status_code == 402  # Payment Required
    assert "limited to 7 days" in response.json()["detail"]

# Test training job quota
def test_training_job_daily_quota_starter():
    # First job succeeds
    response1 = client.post(
        "/api/v1/tenant123/training-jobs",
        json={"dataset_rows": 500},
        headers={"Authorization": f"Bearer {starter_admin_token}"}
    )
    assert response1.status_code == 200

    # Second job on same day fails (1/day limit)
    response2 = client.post(
        "/api/v1/tenant123/training-jobs",
        json={"dataset_rows": 500},
        headers={"Authorization": f"Bearer {starter_admin_token}"}
    )
    assert response2.status_code == 429  # Too Many Requests

Integration Tests

# Test tenant isolation
def test_user_cannot_access_other_tenant():
    response = client.get(
        "/api/v1/tenant456/sales",  # Different tenant
        headers={"Authorization": f"Bearer {user_token}"}
    )
    assert response.status_code == 403

Security Tests

# Test rate limiting
def test_training_job_rate_limit():
    for i in range(6):
        response = client.post(
            "/api/v1/tenant123/training-jobs",
            headers={"Authorization": f"Bearer {admin_token}"}
        )
    assert response.status_code == 429  # Too Many Requests

Security Documentation

Database Security - Database security implementation
TLS Configuration - TLS/SSL setup details
Security Checklist - Deployment checklist

Source Reports

RBAC Analysis Report - Complete analysis

Code References

shared/auth/access_control.py - Role and tier decorators
shared/auth/tenant_access.py - FastAPI dependencies
services/tenant/app/models/tenants.py - Tenant member model

Document Version: 1.0 Last Review: November 2025 Next Review: February 2026 Owner: Security & Platform Team

19 KiB Raw Blame History

Role-Based Access Control (RBAC) Implementation Guide

Table of Contents

Overview

Key Components

Implementation Status

Role System Architecture

User Role Hierarchy

Permission Matrix by Action

Subscription Tier System

Tier Features Matrix

Access Control Implementation

Available Decorators

Subscription Tier Enforcement

Role-Based Enforcement

Combined Enforcement

FastAPI Dependencies

Service-by-Service RBAC Matrix

Authentication Service

Tenant Service

Sales Service

Inventory Service

Production Service

Forecasting Service

Training Service

Orders Service

Implementation Guidelines

Step 1: Add Role Decorators

Step 2: Add Subscription Tier Checks

Step 3: Add Audit Logging

Step 4: Implement Rate Limiting

Testing Strategy

Unit Tests

Integration Tests

Security Tests

Related Documentation

Security Documentation

Source Reports

Code References

19 KiB

Raw Blame History