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.

Cognito client user group setup

The cognito client must be setup to redirect back to /login-callback for PKCE flow to work.

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.

Cognito auth flow (mermaid)

For a live graph of the auto flow go here.

sequenceDiagram
    participant Browser
    participant AppServer as DoczyApiBE
    participant Cognito
    
    Browser->>AppServer: 1. GET /login
    Note over AppServer: 2. Generate code_verifier<br/>Generate code_challenge
    AppServer->>Browser: 3. Redirect to Cognito
    Browser->>Cognito: 4. GET /oauth2/authorize?...code_challenge
    Note over Cognito: 5. Process auth request
    Cognito->>Browser: 6. Cognito Login Page
    Browser->>Cognito: 7. User credentials
    Note over Cognito: 8. Validate credentials
    Cognito->>Browser: 9. Redirect with code
    Browser->>AppServer: 10. GET /login-callback?code=...
    Note over AppServer: 11. Retrieve code_verifier
    AppServer->>Cognito: 12. POST /oauth2/token<br/>code=...&code_verifier=...
    Note over Cognito: 13. Validate code and verifier
    Cognito->>AppServer: 14. Tokens response
    Note over AppServer: 15. Verify tokens<br/>Check permissions
    AppServer->>Browser: 16. Authentication successful