MSK Authentication

This document describes how authentication works for MSK (Musculoskeletal) Assessment routes when using the GOFA WebView SDK.

Overview

MSK routes (/msk/*) are protected by Firebase authentication. The Flutter WebView SDK obtains a Firebase custom token, passes it via URL parameter, and the server automatically exchanges it for a session cookie on first load. Subsequent navigations use that session cookie — no further token passing is needed.

Authentication Flow

sequenceDiagram
    participant App as Your Flutter App
    participant SDK as GOFA WebView SDK
    participant Server as GOFA Server

    Note over App: 1. SDK initialization
    App->>SDK: init(clientId, clientSecret, clientUserId)
    SDK->>Server: Request custom token
    Server-->>SDK: Firebase custom token

    Note over App: 2. Open WebView
    SDK->>Server: GET /msk/home?customToken=xxx&locale=en
    Server-->>SDK: Page loads, auto sign-in, session cookie set
    Note over SDK: customToken stripped from URL

    Note over App: 3. Subsequent navigations
    SDK->>Server: GET /msk/assessment/123 (session cookie)
    Server-->>SDK: 200 OK (authenticated)

How It Works

First Visit

1. Your app initializes the SDK with clientId, clientSecret, and clientUserId
2. The SDK calls the GOFA backend to obtain a Firebase custom token
3. The SDK opens the MSK URL with the token appended: https://{clientId}.gofa.app/msk/home?customToken=xxx&locale=en
4. The server detects the token, signs the user in, and sets a session cookie
5. The token is automatically removed from the URL for security

Subsequent Navigations

1. All further requests within the WebView use the session cookie automatically
2. No additional token passing is needed
3. The session is automatically refreshed as needed

Subdomain-Client Isolation

MSK URLs are scoped by client subdomain: https://{clientId}.gofa.app/msk/*

The server validates that the authenticated user's token matches the subdomain they are accessing. If there's a mismatch, the user is signed out and redirected.

Security Notes

• The ?customToken parameter is only used on the first page load and is immediately removed from the URL
• Custom tokens are short-lived (1 hour expiry)
• Session cookies are HttpOnly and Secure
• Each client subdomain is isolated — users cannot access a different client's MSK routes

Legacy Basic Auth (Transition Period)

Older Flutter SDK versions used HTTP basic auth for MSK routes. During the transition period, the server can optionally accept basic auth for backward compatibility. Contact your GOFA representative if you need this enabled while migrating.

Migration Steps

1. Update to gofa_webview v1.1.0 or later (v1.2.0+ recommended for client-agnostic features)
2. Remove basicAuthUser and basicAuthPass from your SDK initialization
3. Verify the custom token flow works in your environment
4. Notify your GOFA representative that migration is complete

Flutter SDK Integration

The Flutter WebView SDK handles authentication automatically:

// 1. Initialize the SDK (generates custom token internally)
final manager = WebViewSdkManager();
await manager.init(
  clientId: 'your-client-id',
  clientSecret: '<client-secret>',
  clientUserId: '<gofa-user-id>',
  environment: Environment.PRD,
);

// 2. Open the WebView (customToken added to URL automatically)
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => WebviewScreen(
      url: 'https://your-client.gofa.app/msk/home',
      customToken: manager.customToken,
      locale: const Locale('en'),
    ),
  ),
);

Change History