Component Diagram

The CWMS Access Management system consists of several interconnected components that work together to provide authorization services.

System Component Diagram

        graph TB
    subgraph External
        client[Client Application]
    end

    subgraph Access Management Layer
        proxy[Authorization Proxy]
        opa[Open Policy Agent]
        redis[Redis Cache]
        mgmt_ui[Management UI]
        mgmt_api[Management API]
    end

    subgraph Identity Layer
        keycloak[Keycloak]
    end

    subgraph Data Layer
        cda[CWMS Data API]
        db[(Oracle Database)]
    end

    client --> proxy
    proxy --> opa
    proxy --> redis
    proxy --> cda
    proxy --> keycloak
    cda --> keycloak
    cda --> db
    mgmt_ui --> mgmt_api
    mgmt_api --> opa
    mgmt_api --> keycloak
    

Component Details

Authorization Proxy

The authorization proxy is the entry point for all client requests to the CWMS Data API.

        graph LR
    subgraph Authorization Proxy
        router[Request Router]
        jwt[JWT Parser]
        cache[Cache Client]
        policy[Policy Client]
        context[Context Builder]
        forward[Request Forwarder]
    end

    router --> jwt
    jwt --> cache
    cache --> policy
    policy --> context
    context --> forward
    

Subcomponent	Responsibility
Request Router	Routes incoming requests based on whitelist configuration
JWT Parser	Extracts user identity from JWT tokens
Cache Client	Interfaces with Redis for user context caching
Policy Client	Communicates with OPA for policy evaluation
Context Builder	Constructs the x-cwms-auth-context header
Request Forwarder	Forwards authorized requests to the backend API

Open Policy Agent

OPA provides policy-based authorization decisions using Rego policies.

        graph TB
    subgraph OPA
        engine[Policy Engine]
        policies[Policy Bundle]
    end

    subgraph Policies
        main[cwms_authz.rego]
        personas[Persona Policies]
        helpers[Helper Functions]
    end

    engine --> policies
    policies --> main
    main --> personas
    main --> helpers
    

Policy structure:

Policy File	Purpose
cwms_authz.rego	Main orchestrator policy
personas/public.rego	Anonymous access rules
personas/dam_operator.rego	Operational staff rules
personas/water_manager.rego	Management staff rules
personas/data_manager.rego	Regional manager rules
personas/automated_collector.rego	Data collection system rules
personas/automated_processor.rego	Data processing system rules
personas/external_cooperator.rego	External partner rules
helpers/offices.rego	Office metadata and relationships
helpers/time_rules.rego	Embargo and time window rules

Redis Cache

Redis stores user context to reduce database queries and improve response times.

Configuration	Value
Key Format	user:context:{username}
TTL	1800 seconds (30 minutes)
Max Memory	256 MB
Eviction Policy	allkeys-lru
Persistence	AOF (append-only file)

CWMS Data API

The Java backend API provides data access with authorization filtering.

        graph TB
    subgraph CWMS Data API
        endpoints[REST Endpoints]
        filter[Authorization Filter]
        helper[AuthorizationFilterHelper]
        jooq[JOOQ Query Builder]
    end

    subgraph Database Access
        db[(Oracle Database)]
    end

    endpoints --> filter
    filter --> helper
    helper --> jooq
    jooq --> db
    

Component	Responsibility
REST Endpoints	Handle HTTP requests for various data types
Authorization Filter	Intercepts requests to extract auth context
AuthorizationFilterHelper	Parses header and generates SQL conditions
JOOQ Query Builder	Constructs filtered SQL queries

Keycloak

Keycloak provides identity management and authentication services.

Feature	Usage
User Management	Stores user credentials and attributes
JWT Issuance	Issues tokens upon successful authentication
JWKS Endpoint	Provides public keys for token validation
Realm Configuration	Defines client applications and roles

Management Components

The management UI and API provide administrative interfaces for the access management system.

Component	Technology	Port	Purpose
Management UI	React 18, Vite, Tailwind	4200	Web-based policy management
Management API	Node.js, Fastify	3002	Backend for management operations

Network Topology

All components communicate over a shared container network.

        graph TB
    subgraph cwmsdb_net
        proxy[Authorization Proxy<br/>Port 3001]
        opa[OPA<br/>Port 8181]
        redis[Redis<br/>Port 6379]
        mgmt_ui[Management UI<br/>Port 4200]
        mgmt_api[Management API<br/>Port 3002]
        cda[CWMS Data API<br/>Port 7001]
        keycloak[Keycloak<br/>Port 8080]
        db[Oracle Database<br/>Port 1521]
    end

    proxy --> opa
    proxy --> redis
    proxy --> cda
    mgmt_ui --> mgmt_api
    mgmt_api --> opa
    mgmt_api --> keycloak
    cda --> db
    cda --> keycloak
    

Data Flow Summary

Flow	Path	Data
Client Request	Client to Proxy	JWT token, HTTP request
Context Lookup	Proxy to Redis	Username key
Profile Request	Proxy to API	JWT token
Policy Check	Proxy to OPA	User context, request details
Data Request	Proxy to API	Auth context header, original request
Database Query	API to Oracle	Filtered SQL query

Dependency Graph

        graph TD
    proxy[Authorization Proxy]
    opa[OPA]
    redis[Redis]
    cda[CWMS Data API]
    keycloak[Keycloak]
    db[Oracle Database]
    mgmt_ui[Management UI]
    mgmt_api[Management API]

    proxy --> opa
    proxy --> redis
    proxy --> cda
    cda --> keycloak
    cda --> db
    mgmt_ui --> mgmt_api
    mgmt_api --> opa
    mgmt_api --> keycloak
    

Startup order:

1. Oracle Database

2. Keycloak (depends on database for persistence)

3. Redis (no dependencies)

4. OPA (no dependencies)

5. CWMS Data API (depends on database and Keycloak)

6. Authorization Proxy (depends on Redis, OPA, and CWMS Data API)

7. Management API (depends on OPA and Keycloak)

8. Management UI (depends on Management API)