Construction Automation CA

Setting up role-based access control for subcontractor portals

Implementing role-based access control (RBAC) for subcontractor portals requires precise routing logic and strict compliance enforcement to prevent unauthorized data exposure across project phases, work breakdown structures, and financial boundaries. When architecting these systems, developers must anchor permission models to a standardized Construction Data Architecture & Taxonomy that explicitly maps roles to scoped resources such as RFIs, submittals, change orders, and budget line items. The primary intent of this implementation is routing and compliance enforcement: dynamically evaluating user claims against project-specific boundaries, routing authorized requests to the correct data endpoints, and triggering compliant fallback workflows when access criteria fail validation.

Permission Evaluation Engine

The core routing mechanism relies on a deterministic policy engine that evaluates role assignments, contract validity windows, and resource scoping before granting portal access. Subcontractor roles rarely align with generic enterprise RBAC templates; they require explicit binding to WBS segments, budget codes, and document metadata frameworks. The following Python implementation demonstrates a production-ready routing evaluator that enforces least-privilege access while maintaining audit compliance.

from datetime import datetime, timezone
from typing import Dict, List, Set, Optional, Any
from dataclasses import dataclass, field
import logging

logger = logging.getLogger(__name__)

@dataclass
class AccessContext:
    user_id: str
    role: str
    project_id: str
    requested_resource: str
    resource_wbs: str
    resource_budget_code: str
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

@dataclass
class ContractProfile:
    subcontractor_id: str
    valid_from: datetime
    valid_to: datetime
    assigned_wbs_segments: Set[str]
    authorized_budget_codes: Set[str]
    role_permissions: Dict[str, Set[str]] = field(default_factory=dict)

class RBACRoutingEngine:
    def __init__(self, contract_registry: Dict[str, ContractProfile]):
        self.contract_registry = contract_registry
        self.permission_matrix: Dict[str, Set[str]] = {
            "subcontractor_lead": {"view_rfi", "submit_rfi", "view_submittal", "submit_submittal", "view_change_order"},
            "subcontractor_field": {"view_rfi", "submit_rfi", "view_submittal"},
            "subcontractor_accounting": {"view_change_order", "view_budget"}
        }

    def evaluate_access(self, context: AccessContext, contract_id: str) -> Dict[str, Any]:
        try:
            contract = self.contract_registry.get(contract_id)
            if not contract:
                return self._route_denied(context, "CONTRACT_NOT_FOUND", 404)

            if not (contract.valid_from <= context.timestamp <= contract.valid_to):
                return self._route_denied(context, "CONTRACT_EXPIRED", 403)

            if context.resource_wbs not in contract.assigned_wbs_segments:
                return self._route_denied(context, "WBS_SCOPE_MISMATCH", 403)

            if context.resource_budget_code not in contract.authorized_budget_codes:
                return self._route_denied(context, "BUDGET_SCOPE_MISMATCH", 403)

            allowed_actions = self.permission_matrix.get(context.role, set())
            requested_action = context.requested_resource.split(":")[0] if ":" in context.requested_resource else context.requested_resource

            if requested_action not in allowed_actions:
                return self._route_denied(context, "INSUFFICIENT_ROLE_PRIVILEGES", 403)

            return self._route_granted(context, contract.subcontractor_id)

        except Exception as e:
            logger.error("RBAC evaluation failed for user %s: %s", context.user_id, str(e))
            return self._route_denied(context, "EVALUATION_ERROR", 500)

    def _route_granted(self, context: AccessContext, subcontractor_id: str) -> Dict[str, Any]:
        logger.info("Access granted: user=%s resource=%s", context.user_id, context.requested_resource)
        return {
            "status": "ALLOWED",
            "route": f"/api/v1/projects/{context.project_id}/resources/{context.requested_resource}",
            "context": {"subcontractor_id": subcontractor_id, "audit_id": context.user_id}
        }

    def _route_denied(self, context: AccessContext, reason: str, status_code: int) -> Dict[str, Any]:
        logger.warning("Access denied: user=%s reason=%s status=%d", context.user_id, reason, status_code)
        return {
            "status": "DENIED",
            "reason": reason,
            "status_code": status_code,
            "fallback_route": "/api/v1/portals/access-denied",
            "audit_payload": {
                "user_id": context.user_id,
                "project_id": context.project_id,
                "timestamp": context.timestamp.isoformat(),
                "violation_type": reason
            }
        }

WBS and Budget Boundary Enforcement

Subcontractor access must be constrained to the exact scope of work defined in executed agreements. The evaluation engine above validates resource_wbs and resource_budget_code against the ContractProfile before proceeding. This prevents lateral movement across unrelated project phases or cost centers. When integrating with existing ERP or project management systems, ensure that WBS hierarchies and budget codes are normalized to a consistent format. Refer to established Security Boundary Configuration patterns to isolate tenant data and prevent cross-project leakage during multi-contractor deployments.

Estimators and project managers should verify that budget code mappings align with the CSI MasterFormat or company-specific cost accounting standards. Misaligned codes will trigger BUDGET_SCOPE_MISMATCH denials, which are intentionally strict to maintain financial audit integrity.

Fallback Routing and Audit Compliance

When access validation fails, the system must never expose partial data or return ambiguous HTTP statuses. The _route_denied method returns a structured payload containing a safe fallback route and a complete audit payload. This design ensures that:

  1. Unauthorized requests are logged deterministically for compliance reviews and security audits.
  2. Subcontractor portals render context-appropriate messaging without leaking internal routing paths or project metadata.
  3. Automated alerting systems can ingest the audit_payload to trigger notifications for expired contracts or repeated scope violations.

For regulatory alignment, implement structured logging that captures the exact evaluation timestamp, user identity, and violation reason. This approach satisfies NIST SP 800-53 Access Control (AC-3) requirements for least-privilege enforcement and audit trail generation.

Implementation Checklist

  1. Normalize Role Definitions: Map subcontractor titles (subcontractor_lead, subcontractor_field, subcontractor_accounting) to explicit action sets. Avoid wildcard permissions.
  2. Validate Contract Windows: Ensure valid_from and valid_to timestamps are timezone-aware and synchronized with project execution calendars.
  3. Bind WBS Segments Programmatically: Ingest WBS assignments directly from executed change orders or prime contracts. Do not rely on manual portal configuration.
  4. Test Boundary Conditions: Run integration tests against expired contracts, mismatched budget codes, and unauthorized role escalations. Verify that the engine returns DENIED with accurate status_code values.
  5. Deploy with Structured Logging: Route evaluation logs to a centralized SIEM or compliance dashboard. Use Python’s logging module with JSON formatters for machine-readable audit trails.

Adhering to these steps ensures that subcontractor portals operate within strict security boundaries while maintaining seamless routing for authorized workflows. For additional guidance on type-safe contract validation, consult the official Python typing documentation.