query-orchestration/internal/cognitoauth/summary.md

Cognito RBAC Design and Integration

Overview

This package uses AWS Cognito for authentication and implements Role-Based Access Control (RBAC) for API endpoints. The integration is tightly coupled with the Echo web framework and the OpenAPI (swagger) generated API code.

Key Components

1. Cognito Auth Package (internal/cognitoauth)

• auth.go: Main exports for the package.
• handler.go: HTTP handlers for login, callback, logout, and home.
• middleware.go: Echo middleware for JWT extraction, validation, and RBAC enforcement.
• jwks.go: Handles JWKS key fetching and JWT signature validation.
• token.go: Token verification and management.
• models.go: Data models and types for tokens, users, etc.
• utils.go: Helper functions.
• config.go: Configuration structures for the auth system.

2. Service Config (internal/serviceconfig)

• auth/config.go: Loads and manages authentication-related configuration, including RBAC route permissions.
• common.go: Shared config logic.

3. API Layer (api/queryAPI)

• api.gen.go: Swagger-generated API handlers.
• authHandlers.go: Bridges generated code to Cognito logic; delegates to middleware for most flows.
• homehandler.go: Displays authentication status.
• controllers.go: Wires up controllers, but does not directly handle auth.

4. Server Setup (internal/server/api/listener.go)

• Creates the Echo server.
• Sets up config and logging middleware.
• Sets up Prometheus and OpenAPI validation middleware.
• Registers Cognito RBAC middleware and routes before registering API handlers.
• Sets route-level permissions via a map of route to allowed groups.

Integration Flow

1. Config Initialization: Auth config and route permissions are loaded at startup.
2. Echo Server Setup: The Echo instance is created and set on the config.
3. RBAC Middleware Registration:
   • cognitoauth.RegisterRoutes(echoRouter, config) is called.
   • This registers login, callback, logout, and home endpoints.
   • It also registers JWT extraction and validation middleware.
   • Route permissions are enforced via middleware that checks the user's Cognito groups/roles against the configured permissions map.
4. API Handler Registration:
   • OpenAPI-generated handlers are registered after the RBAC middleware.
   • All API endpoints are thus protected by the RBAC middleware.
5. Request Flow:
   • User requests a protected endpoint.
   • Middleware extracts JWT from cookies, validates it, and checks group membership.
   • If authorized, the request proceeds to the handler (which may be swagger-generated).
   • If not, a 401/403 is returned.

Example

// Set route permissions
routePermissions := map[string][]string{
    "/users": {"exporters", "uploaders", "querybuilders"},
    "/orders": {"exporters"},
    // ...
}
config.SetAuthRoutePermissions(routePermissions)

// Register Cognito auth routes and middleware
cognitoauth.RegisterRoutes(echoRouter, config)

// Register API handlers (swagger-generated)
RegisterHandlers(echoRouter, controllers)

Customization

• Paths for login, callback, logout, and home can be configured.
• Route permissions are fully customizable.
• Middleware can be extended or replaced for fine-grained control.
• User info is accessible in handlers via helper functions.