MSK Authentication

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

info

As of February 2026, MSK routes use Firebase custom token authentication instead of HTTP basic auth. This change provides per-client access control via subdomain-based validation.

---

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

---

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.

Scenario	Result
Token matches subdomain client	Access granted
Token does not match subdomain	Signed out, redirected
No session / expired session	Redirected to sign in
First visit with ?customToken	Auto sign-in, session created

---

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)

warning

Legacy basic auth support is temporary and will be removed in a future release.

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'),
    ),
  ),
);

note

The basicAuthUser and basicAuthPass parameters on WebViewSdkManager are deprecated as of gofa_webview v1.1.0. You can safely remove them from your code.

---

Change History

Date	Change
2026-02-11	Initial version. Documented Firebase custom token auth flow replacing HTTP Basic Auth.