jay brown
82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```go
|
|
// 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.
|