OAuth2 UI Request Authentication

This document describes the standard Cognito-based authentication flow for UI requests, without a custom claims server.

JWT Contents

The JWT issued by Cognito contains:

• sub — user ID
• scope — granted OAuth2 scopes
• custom:tenant — tenant ID (optional)
• Additional custom claims as configured

Simple Scenario: No Custom Claims Server

The authentication path for a user action:

1. Browser → BFF: Request with JWT. BFF validates the JWT with the Cognito Client App to ensure it is current; otherwise redirects to sign-in.
2. BFF → API Gateway: Forwards the request with JWT (and optional Tenant ID header).
3. API Gateway → Authorizer: Validates JWT signature, claims, and expiry against the Cognito Client App. Returns a validated JWT constrained to available scopes.
4. API Gateway → Component: Forwards the request with the validated JWT.
5. Component → Ktor OAuth2: Performs a second validation (defense-in-depth against requests that bypass the API Gateway). This step is optional.
6. Component → Service: Service uses the ApplicationContext derived from the validated JWT to enforce RBAC/ABAC access control on all data operations.

Custom Claims with Token Exchange (Future)

A planned future extension adds an Authentication Lambda that calls a Claims Endpoint during token validation. The lambda injects additional claims (e.g., tenant-specific permissions) into the token at the API Gateway authorization step. This pattern is still preliminary and depends on future Cognito capabilities.