BFF layer between frontends and the backend (Platform API)

[malinthaprasan]

Summary

Today our frontends talk to the API Platform backend directly:

AI Workspace        ─┐
Management Console  ─┤──►  API Platform (single backend)
(other services)    ─┘

The API Platform operates as a single backend for multiple frontends, and is also called internally by other services. Because of this, frontend-specific requirements (cookie handling, view-shaped aggregations, login flows, etc.) tend to leak into the Platform API's REST contract and pollute a backend that is meant to be frontend-agnostic.

This proposes a Backend-for-Frontend (BFF) layer between each frontend and the Platform API.

Proposed architecture

AI Workspace        ──►  AI Workspace BFF        ──►  API Platform
Management Console   ──►  Management Console BFF  ──►  API Platform

Each frontend gets its own BFF. And also note that the BFF is not a new server component to operate separately. It is a Go server that also hosts the React UI for that frontend. So we are not adding an extra deployable per frontend; the BFF is the frontend's serving host.

The BFF owns everything that is specific to its frontend:

• Serving the React app (static assets + SPA routing).
• Login / session handling for that frontend.
• Cookie/session ↔ Platform API auth conversions.
• Any view-specific shaping or aggregation of Platform API responses.

The Platform API keeps a clean, frontend-agnostic contract.

Request paths (AI Workspace example)

Purpose	Path
App load	GET https://ai-workspace-host:port/console
Login (frontend-specific)	https://ai-workspace-host:port/console/api/login
All other backend calls	https://ai-workspace-host:port/console/api/proxy/{path}

/console/api/proxy/{path} is handled by the BFF's Go code: it performs any frontend-specific cookie/session conversions, then forwards the request to the Platform API backend.

sequenceDiagram
    participant B as Browser (AI Workspace UI)
    participant BFF as AI Workspace BFF (Go)
    participant API as API Platform

    B->>BFF: GET /console
    BFF-->>B: React app (static assets + SPA)

    B->>BFF: POST /console/api/login
    BFF->>API: Validate user
    API-->>BFF: User validated
    BFF-->>B: Login response

    B->>BFF: GET /console/api/rest-apis/{id}/overview
    Note over BFF: Frontend-specific aggregation
    BFF->>API: GET /rest-apis/{id}
    API-->>BFF: APIs
    BFF->>API: GET /rest-apis/{id}/analytics
    API-->>BFF: analytics
    BFF-->>B: combined dashboard response

    B->>BFF: /console/api/proxy/{path}
    Note over BFF: Frontend-specific auth conversion
    BFF->>API: forward {path} (Platform API auth)
    API-->>BFF: response
    BFF-->>B: response

Loading

Benefits

1. Keeps the Platform API contract clean — frontend-specific concerns live in the BFF, not in the shared backend.
2. No extra server to operate — the BFF Go server already hosts the React UI, so there is no new standalone component per frontend.
3. Per-frontend isolation — AI Workspace and Management Console can evolve their own session/cookie/login behavior independently.
4. Single trusted hop to the backend — cross-origin/cookie complexity is handled server-side in the BFF rather than in the browser.
5. Same-origin frontend — the UI and its /api/* endpoints share one origin, which simplifies cookies, CORS, and CSRF handling.

[Thushani-Jayasekera]

Portals will support File based login and IDP login

According to the above discussion,
The proposed Full sequence flow for IDP Login & File-based Login for AI Workspace Portal will be as below,

1. IDP Login

sequenceDiagram
    actor User
    participant B as Browser (AI Workspace UI)
    participant BFF as AI Workspace BFF (Go)
    participant IDP as Identity Provider
    participant API as Platform API

    B->>BFF: GET /console
    BFF-->>B: React SPA (static assets)
    B->>BFF: GET /console/api/auth/config
    BFF-->>B: oidcEnabled true, idpName Asgardeo
    Note over B: Renders Sign in with Asgardeo button
    User->>B: Click Sign in with Asgardeo

    B->>BFF: GET /console/api/auth/login
    # Note over BFF: Generates random state value
    BFF-->>B: 302 to IDP /authorize with client_id, redirect_uri, scope, state
    Note over BFF: Set-Cookie auth_state HttpOnly Secure MaxAge 300

    B->>IDP: GET /authorize
    IDP-->>B: IDP Login Page
    User->>IDP: Enter credentials
    IDP-->>B: 302 to /console/api/auth/callback with AUTH_CODE and state

    B->>BFF: GET /console/api/auth/callback with AUTH_CODE, state, cookie auth_state
    # Note over BFF: Validates state matches cookie
    # Note over BFF: Clears auth_state cookie

    BFF->>IDP: POST /token with client_id, client_secret, AUTH_CODE, grant_type, redirect_uri
    Note over IDP: CLIENT_SECRET never leaves the BFF
    IDP-->>BFF: access_token and id_token
    BFF-->>B: 302 to /console
    Note over BFF: Set-Cookie ap_session toke HttpOnly Secure SameSite Lax MaxAge 28800
    Note over BFF: Set-Cookie auth_state cleared MaxAge -1

    B->>BFF: GET /console/api/proxy/api/v1/organizations with cookie ap_session
    BFF->>API: GET /api/v1/organizations with Authorization Bearer access_token
    API-->>BFF: 200 organizations list
    BFF-->>B: 200 organizations list

    User->>B: Click Logout
    B->>BFF: POST /console/api/auth/logout with cookie ap_session
    # Note over BFF: Clears session cookie
    BFF-->>B: 302 to IDP /logout with post_logout_redirect_uri
    Note over BFF: Set-Cookie ap_session cleared MaxAge -1

    B->>IDP: GET /logout
    IDP-->>B: 302 to /console/login

Loading

2. File Based Login

Note: Platform API owns user validation — it exposes a dedicated /api/v1/auth/user/validate endpoint that handles credential verification and JWT signing. The BFF simply forwards credentials and stores the resulting token; it has no knowledge of users or password hashes.

sequenceDiagram
    actor User
    participant B as Browser (AI Workspace UI)
    participant BFF as AI Workspace BFF (Go)
    participant API as Platform API

    B->>BFF: GET /console
    BFF-->>B: React SPA (static assets)
    B->>BFF: GET /console/api/auth/config
    BFF-->>B: oidcEnabled false, localEnabled true
    Note over B: Renders username + password login form

    User->>B: Enter username + password
    B->>BFF: POST /console/api/auth/login with username and password
    Note over BFF: Forwards credentials to Platform API
    Note over BFF: BFF has no knowledge of users or password hashes

    BFF->>API: POST /api/v1/auth/user/validate with username and password
    Note over API: 1. Look up user in config
    Note over API: 2. bcrypt.Compare(password, storedHash)
    Note over API: 3. Build JWT claims: sub, username, email, org, scope, iss, exp
    Note over API: 4. Sign with AUTH_JWT_SECRET_KEY

    API-->>BFF: 200 with signed access_token
    Note over BFF: Sets token directly as cookie
    Note over BFF: HttpOnly blocks JS access
    Note over BFF: SameSite Strict blocks cross-site requests

    BFF-->>B: 200 OK
    Note over BFF: Set-Cookie ap_session signed_jwt HttpOnly Secure SameSite Strict MaxAge 28800
    Note over B: React redirects to /console, no token in storage

    B->>BFF: GET /console/api/proxy/api/v1/organizations with cookie ap_session
    Note over BFF: Reads token directly from cookie
    BFF->>API: GET /api/v1/organizations with Authorization Bearer signed_jwt
    Note over API: Validates HMAC signature using AUTH_JWT_SECRET_KEY
    Note over API: Extracts organization and scope claims

    API-->>BFF: 200 organizations list
    BFF-->>B: 200 organizations list

    User->>B: Click Logout
    B->>BFF: POST /console/api/auth/logout with cookie ap_session
    Note over BFF: Clears session cookie, no IDP logout needed
    BFF-->>B: 200 OK
    Note over BFF: Set-Cookie ap_session cleared MaxAge -1
    Note over B: React redirects to /console/login

Loading

Configs

BFF (all new)

Both modes

│          Config          │           Env var            │          Example          │
├──────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ Platform API URL         │ PLATFORM_API_URL             │ https://platform-api:9243 │
├──────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ Skip TLS verify          │ PLATFORM_API_TLS_SKIP_VERIFY │ true (dev) / false (prod) │
├──────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ Enable local auth        │ AUTH_LOCAL_ENABLED           │ true                      │
├──────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ Cookie max age (seconds) │ COOKIE_MAX_AGE               │ 28800                     │
└──────────────────────────┴──────────────────────────────┴───────────────────────────┘

IDP mode

┌──────────────────────┬───────────────────────────────────┬───────────────────────────────────────────────────┐
│        Config        │              Env var              │                      Example                      │
├──────────────────────┼───────────────────────────────────┼───────────────────────────────────────────────────┤
│ Client secret        │ AUTH_IDP_CLIENT_SECRET            │ s3cr3t...                                         │
├──────────────────────┼───────────────────────────────────┼───────────────────────────────────────────────────┤
│ Callback URL         │ AUTH_IDP_REDIRECT_URI             │ https://app.example.com/console/api/auth/callback │
├──────────────────────┼───────────────────────────────────┼───────────────────────────────────────────────────┤
│ Post-logout redirect │ AUTH_IDP_POST_LOGOUT_REDIRECT_URI │ https://app.example.com/console/login             │
└──────────────────────┴───────────────────────────────────┴───────────────────────────────────────────────────┘

---

Platform API (new for file-based only)

│           Config           │        Env var        │           Example            │
 ├────────────────────────────┼───────────────────────┼──────────────────────────────┤
 │ Enable local auth endpoint │ AUTH_LOCAL_ENABLED    │ true                         │
 ├────────────────────────────┼───────────────────────┼──────────────────────────────┤
 │ Users file path            │ AUTH_LOCAL_USERS_FILE │ /etc/platform-api/users.yaml │
 ├────────────────────────────┼───────────────────────┼──────────────────────────────┤
 │ JWT expiry (seconds)       │ AUTH_JWT_EXPIRY       │ 28800                        │
 └────────────────────────────┴───────────────────────┴──────────────────────────────┘

users.yaml — new file, lives on platform-api side:

users:
   - username: alice
     passwordHash: "$2a$12$..."
     organization: "org-uuid-here"
     scopes:
       - ap:organization:read
       - ap:rest_api:manage

Please share your thoughts.

Thanks