WEB-956: share auth session across tabs and preserve deep links

Currently AuthenticationService persists the user credentials in
sessionStorage by default, which is scoped to a single browser tab. As
a result, any link to a Mifos URL opened from outside the current tab
— email, chat, bookmark, target="_blank", a new browser window — boots
into an empty storage and the AuthenticationGuard sends the
already-logged-in user back to /login. Compounding this,
AuthenticationGuard does not propagate the requested URL and
LoginComponent unconditionally navigates to "/" after a successful
login, so the originally requested deep link is permanently lost.

This change adopts the pattern used by `@supabase/auth-js`
(GoTrueClient.ts) and Auth0's SPA SDK: localStorage as the single
source of truth for the session, plus a BroadcastChannel for
cross-tab synchronisation. It also makes the guard forward the
target URL through the login flow.

- AuthenticationService.storage is now localStorage unconditionally,
  so the session is visible to every tab/window of the same origin.
  The `rememberMe` flag is preserved for the backend token-expiration
  policy but no longer chooses the Storage instance.
- getSavedCredentials() prefers localStorage and performs a one-time
  migration of any leftover sessionStorage credentials so existing
  users do not get stranded after the upgrade.
- A BroadcastChannel named `mifosXAuth` is created lazily (with a
  feature-detect fallback). Login broadcasts `{ type: 'login' }`,
  logout broadcasts `{ type: 'logout' }`; the listener uses
  hadPersistedCredentials to fire the login broadcast even though
  onLoginSuccess() flips userLoggedIn$ before setCredentials() runs.
- The cross-tab logout handler now also clears the two-factor token
  storage and the two-factor authorization header, mirroring what
  logout() does on the active tab.
- AuthenticationGuard.canActivate now accepts RouterStateSnapshot and
  forwards state.url as a returnUrl query parameter when the target
  is a meaningful route. Trivial targets ("/", "/login") are skipped
  to avoid noise and redirect loops.
- LoginComponent reads queryParamMap.get('returnUrl') from the
  ActivatedRoute when the authentication success alert fires, and
  navigates there via navigateByUrl. Falls back to "/" when no
  returnUrl is present.
- Adds unit tests for the guard covering: authenticated pass-through,
  deep-link capture, "/" and "/login" being skipped to avoid
  loops/noise, stale-params handling, and URLs with query params
  plus fragments.

Verified end-to-end against an isolated docker-compose stack
(postgres + fineract + web-app):

  before: /#/clients -> /#/login -> /#/home              (bug)
  after:  /#/clients -> /#/login?returnUrl=/clients -> /#/clients

  cross-tab logout: tab A logs out -> tab B reacts live.

Addresses CodeRabbit review feedback:
- getSavedCredentials() now treats localStorage as authoritative and
  migrates legacy sessionStorage credentials once.
- Cross-tab logout handler also clears 2FA state.
- Login broadcast is gated on persisted credentials, not on
  userLoggedIn$, so a fresh login is correctly announced to other
  tabs even though onLoginSuccess() sets userLoggedIn$ first.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Jonattan Infante

src/app/core/authentication/authentication.guard.spec.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright since 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+import { TestBed } from '@angular/core/testing';
+import { ActivatedRouteSnapshot, Router, RouterStateSnapshot } from '@angular/router';
+
+import { AuthenticationGuard } from './authentication.guard';
+import { AuthenticationService } from './authentication.service';
+
+describe('AuthenticationGuard', () => {
+  let guard: AuthenticationGuard;
+  let authServiceMock: jest.Mocked<Pick<AuthenticationService, 'isAuthenticated' | 'logout'>>;
+  let routerMock: jest.Mocked<Pick<Router, 'navigate'>>;
+
+  const buildState = (url: string): RouterStateSnapshot => ({ url }) as RouterStateSnapshot;
+  const emptyRoute = {} as ActivatedRouteSnapshot;
+
+  beforeEach(() => {
+    authServiceMock = {
+      isAuthenticated: jest.fn(),
+      logout: jest.fn()
+    };
+    routerMock = { navigate: jest.fn() };
+
+    TestBed.configureTestingModule({
+      providers: [
+        AuthenticationGuard,
+        { provide: AuthenticationService, useValue: authServiceMock },
+        { provide: Router, useValue: routerMock }]
+    });
+
+    guard = TestBed.inject(AuthenticationGuard);
+  });
+
+  it('allows the route when user is authenticated', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(true);
+    const result = guard.canActivate(emptyRoute, buildState('/clients'));
+    expect(result).toBe(true);
+    expect(routerMock.navigate).not.toHaveBeenCalled();
+    expect(authServiceMock.logout).not.toHaveBeenCalled();
+  });
+
+  it('redirects to /login with returnUrl when target is a deep link', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    const result = guard.canActivate(emptyRoute, buildState('/clients/1/general'));
+    expect(result).toBe(false);
+    expect(authServiceMock.logout).toHaveBeenCalledTimes(1);
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], {
+      queryParams: { returnUrl: '/clients/1/general' },
+      replaceUrl: true
+    });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is "/" (default landing)', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is already /login (avoids loops)', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/login'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('redirects to /login WITHOUT returnUrl when target is /login with stale params', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    guard.canActivate(emptyRoute, buildState('/login?returnUrl=/foo'));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], { queryParams: {}, replaceUrl: true });
+  });
+
+  it('preserves complex URLs with query params and fragments', () => {
+    authServiceMock.isAuthenticated.mockReturnValue(false);
+    const target = '/loans/42?tab=schedule#repayment';
+    guard.canActivate(emptyRoute, buildState(target));
+    expect(routerMock.navigate).toHaveBeenCalledWith(['/login'], {
+      queryParams: { returnUrl: target },
+      replaceUrl: true
+    });
+  });
+});

src/app/core/authentication/authentication.guard.ts

@@ -8,7 +8,7 @@
 
 /** Angular Imports */
 import { Injectable, inject } from '@angular/core';
-import { Router } from '@angular/router';
+import { ActivatedRouteSnapshot, Router, RouterStateSnapshot } from '@angular/router';
 
 /** Custom Services */
 import { Logger } from '../logger/logger.service';
@@ -26,18 +26,34 @@ export class AuthenticationGuard {
   private authenticationService = inject(AuthenticationService);
 
   /**
-   * Ensures route access is authorized only when user is authenticated, otherwise redirects to login.
+   * Ensures route access is authorized only when user is authenticated.
    *
+   * If unauthenticated, redirects to /login while preserving the originally
+   * requested URL in the `returnUrl` query param so the LoginComponent can
+   * restore it after a successful authentication.
+   *
+   * @param _route Activated route snapshot (unused, kept for guard signature).
+   * @param state  Router state — provides the URL the user was trying to reach.
    * @returns {boolean} True if user is authenticated.
    */
-  canActivate(): boolean {
+  canActivate(_route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {
     if (this.authenticationService.isAuthenticated()) {
       return true;
     }
 
-    log.debug('User not authenticated, redirecting to login...');
+    log.debug(`User not authenticated, redirecting to login (target was: ${state.url})...`);
     this.authenticationService.logout();
-    this.router.navigate(['/login'], { replaceUrl: true });
+
+    // Preserve the originally requested URL so the user can be sent back
+    // there after authenticating. We only forward non-trivial targets
+    // (avoid carrying "/" or "/login" as the returnUrl).
+    const targetUrl = state.url;
+    const isMeaningfulTarget = targetUrl && targetUrl !== '/' && !targetUrl.startsWith('/login');
+
+    this.router.navigate(['/login'], {
+      queryParams: isMeaningfulTarget ? { returnUrl: targetUrl } : {},
+      replaceUrl: true
+    });
     return false;
   }
 }

src/app/core/authentication/authentication.service.ts

@@ -58,13 +58,17 @@ export class AuthenticationService {
   /** Denotes whether the user credentials should persist through sessions. */
   private rememberMe = false;
   /**
-   * Denotes the type of storage:
+   * Credentials are always persisted in localStorage so the authenticated
+   * session is shared across browser tabs and windows of the same origin.
+   * sessionStorage would scope the credentials to a single tab, which forces
+   * an unnecessary re-login when the user opens any internal link from an
+   * external program (email, chat, bookmark, target="_blank", etc.).
    *
-   * Session Storage: User credentials should not persist through sessions.
-   *
-   * Local Storage: User credentials should persist through sessions.
+   * The `rememberMe` flag still controls the token expiration policy on the
+   * backend; on logout (or when credentials are cleared explicitly) the
+   * storage is wiped from both localStorage and sessionStorage.
    */
-  private storage: Storage = sessionStorage;
+  private storage: Storage = localStorage;
   private credentials: Credentials;
   private dialogShown = false;
   private authMode: AuthMode = AuthMode.Basic;
@@ -77,6 +81,17 @@ export class AuthenticationService {
   /** Key to store two factor authentication token in storage. */
   private readonly twoFactorAuthenticationTokenStorageKey = 'mifosXTwoFactorAuthenticationToken';
 
+  /**
+   * Broadcast channel used to synchronise login/logout events across browser
+   * tabs and windows of the same origin. Mirrors the pattern used by
+   * `@supabase/auth-js` (see supabase/auth-js GoTrueClient.ts) so that a
+   * logout in any tab propagates to the others without waiting for a page
+   * reload, and a login in a new tab updates already-open ones too.
+   * Falls back gracefully when BroadcastChannel is unavailable.
+   */
+  private readonly broadcastChannel: BroadcastChannel | null =
+    typeof BroadcastChannel !== 'undefined' ? new BroadcastChannel('mifosXAuth') : null;
+
   /**
    * Initializes the type of storage and authorization headers depending on whether
    * credentials are presently in storage or not.
@@ -93,6 +108,35 @@ export class AuthenticationService {
     }
 
     this.restoreSession();
+    this.listenForCrossTabAuthEvents();
+  }
+
+  /**
+   * Listens for login/logout events broadcast from other tabs and updates
+   * the local authentication state accordingly. This keeps the UI in sync
+   * (e.g. a logout in tab A removes the session from tab B in real-time).
+   */
+  private listenForCrossTabAuthEvents(): void {
+    if (!this.broadcastChannel) return;
+    this.broadcastChannel.onmessage = (event: MessageEvent<{ type: 'login' | 'logout' }>) => {
+      if (event.data?.type === 'logout' && this.userLoggedIn$.getValue()) {
+        // Mirror the logout effects without re-broadcasting (avoid loops).
+        // Includes 2FA state to match what logout() clears on the active tab.
+        this.authenticationInterceptor.removeAuthorization();
+        this.authenticationInterceptor.removeTwoFactorAuthorization();
+        [
+          localStorage,
+          sessionStorage
+        ].forEach((store) => {
+          store.removeItem(this.credentialsStorageKey);
+          store.removeItem(this.twoFactorAuthenticationTokenStorageKey);
+        });
+        this.userLoggedIn$.next(false);
+      } else if (event.data?.type === 'login' && !this.userLoggedIn$.getValue()) {
+        // Another tab logged in: rehydrate from shared storage.
+        this.restoreSession();
+      }
+    };
   }
 
   /**
@@ -186,9 +230,21 @@ export class AuthenticationService {
    * @returns {Credentials | null} Stored credentials or null when absent.
    */
   private getSavedCredentials(): Credentials | null {
-    const stored =
-      sessionStorage.getItem(this.credentialsStorageKey) || localStorage.getItem(this.credentialsStorageKey);
-    return stored ? JSON.parse(stored) : null;
+    // localStorage is the authoritative source for the shared session.
+    const local = localStorage.getItem(this.credentialsStorageKey);
+    if (local) return JSON.parse(local);
+
+    // One-time migration: any credentials still lingering in
+    // sessionStorage from older builds are promoted to localStorage
+    // so the session is shared across tabs going forward.
+    const legacySession = sessionStorage.getItem(this.credentialsStorageKey);
+    if (legacySession) {
+      localStorage.setItem(this.credentialsStorageKey, legacySession);
+      sessionStorage.removeItem(this.credentialsStorageKey);
+      return JSON.parse(legacySession);
+    }
+
+    return null;
   }
 
   /**
@@ -220,7 +276,10 @@ export class AuthenticationService {
     }
 
     this.rememberMe = environment.enableRememberMe ? (loginContext?.remember ?? false) : false;
-    this.storage = this.rememberMe ? localStorage : sessionStorage;
+    // Always use localStorage so the authenticated session is visible
+    // to any tab/window opened against the same origin (links from
+    // email, chat, bookmarks, target="_blank", new browser windows, ...).
+    this.storage = localStorage;
 
     // Basic Auth: Direct authentication with Fineract
     return this.http
@@ -374,6 +433,7 @@ export class AuthenticationService {
     this.setCredentials();
     this.resetDialog();
     this.userLoggedIn$.next(false);
+    this.broadcastChannel?.postMessage({ type: 'logout' });
 
     if (this.authMode === AuthMode.OIDC) {
       // OIDC: Use library to handle logout (redirects to OIDC provider)
@@ -435,11 +495,19 @@ export class AuthenticationService {
    */
   private setCredentials(credentials?: Credentials): void {
     if (credentials) {
+      // Capture whether credentials were already persisted BEFORE we write
+      // them. We cannot rely on userLoggedIn$ here because onLoginSuccess()
+      // sets it to `true` before calling setCredentials(), which would make
+      // every login look like a no-op refresh and skip the cross-tab broadcast.
+      const hadPersistedCredentials = !!this.getSavedCredentials();
       credentials.rememberMe = this.rememberMe;
-      // Make sure we're using the correct storage based on rememberMe value
-      this.storage = credentials.rememberMe ? localStorage : sessionStorage;
+      // Credentials are always written to localStorage so the session is
+      // shared across tabs/windows of the same origin (see class doc).
+      this.storage = localStorage;
       this.oauthService.setStorage(this.storage);
       this.storage.setItem(this.credentialsStorageKey, JSON.stringify(credentials));
+      // Notify other tabs only on a NEW login (not on every credential refresh).
+      if (!hadPersistedCredentials) this.broadcastChannel?.postMessage({ type: 'login' });
     } else {
       // Clear credentials from both storage types to ensure complete logout
       [

src/app/login/login.component.ts

@@ -8,7 +8,7 @@
 
 /** Angular Imports */
 import { ChangeDetectionStrategy, Component, OnInit, OnDestroy, inject } from '@angular/core';
-import { Router } from '@angular/router';
+import { ActivatedRoute, Router } from '@angular/router';
 
 /** rxjs Imports */
 
@@ -86,6 +86,7 @@ export class LoginComponent implements OnInit, OnDestroy {
   private settingsService = inject(SettingsService);
   private themingService = inject(ThemingService);
   private router = inject(Router);
+  private activatedRoute = inject(ActivatedRoute);
 
   private versionService = inject(VersionService);
   private translateService = inject(TranslateService);
@@ -143,7 +144,10 @@ export class LoginComponent implements OnInit, OnDestroy {
       } else if (alertType === this.translateService.instant('errors.auth.success.type')) {
         this.resetPassword = false;
         this.twoFactorAuthenticationRequired = false;
-        this.router.navigate(['/'], { replaceUrl: true });
+        const returnUrl = this.activatedRoute.snapshot.queryParamMap.get('returnUrl');
+        // Restore the originally requested deep link if the AuthenticationGuard captured one.
+        // Falls back to root (default landing) when no returnUrl is present.
+        this.router.navigateByUrl(returnUrl || '/', { replaceUrl: true });
       } else if (alertType === this.translateService.instant('errors.tenant.changed.type')) {
         this.updateLogo();
       }