Session Monitoring

Overview

For applications that need to react to session changes in real time, @authrim/web provides a small set of browser-side coordination helpers. They cover cross-tab synchronization, OIDC OP session checks, front-channel logout handling, and the lower-level check_session_iframe transport.

Feature	Purpose	Browser Support
Tab Sync	Coordinate auth state and leader election across browser tabs	Modern browsers with BroadcastChannel
Session Monitor	Poll the OP check_session_iframe for OIDC session changes	Limited by iframe and third-party cookie behavior
Front-Channel Logout	Validate logout requests loaded by the OP in an iframe	Limited by iframe and browser storage behavior
Check Session Iframe	Low-level postMessage wrapper around check_session_iframe	Limited by iframe and third-party cookie behavior

Note

SessionMonitor is an OIDC OP-session monitor. It does not call Authrim’s application session endpoint. For app-level session checks, run your own interval that calls auth.session.validate() or auth.session.get() and use Tab Sync to fan out logout or session-change events across tabs.

Tab Sync

TabSyncManager uses BroadcastChannel to notify other tabs about session changes and logout. It also elects one active leader tab, which is useful when only one tab should run periodic work.

Usage

import { TabSyncManager } from '@authrim/web';

const tabSync = new TabSyncManager({
  channelName: 'authrim-session',
  heartbeatIntervalMs: 5000,
  leaderTimeoutMs: 15000,
});

tabSync.initialize();

const unsubscribeLeader = tabSync.onLeaderChange((isLeader) => {
  if (isLeader) {
    console.log('This tab is now responsible for background checks');
  }
});

// Broadcast when this tab observes a new session state.
const sessionResponse = await auth.session.get();
tabSync.broadcastSessionChange(sessionResponse.data?.session ?? null);

// Broadcast logout after clearing local auth state.
tabSync.broadcastLogout();

window.addEventListener('beforeunload', () => {
  unsubscribeLeader();
  tabSync.destroy();
});

Events

If you pass a compatible eventEmitter, the manager emits session:sync for cross-tab session changes, logout, and leader changes. Without an emitter, you can still use onLeaderChange() and manually call broadcastSessionChange() or broadcastLogout() from your auth flow.

Parameters

Parameter	Type	Default	Description
channelName	string	'authrim-session'	BroadcastChannel name
heartbeatIntervalMs	number	5000	Leader heartbeat interval
leaderTimeoutMs	number	15000	Time before another tab can claim leadership
eventEmitter	EventEmitter	-	Optional SDK event emitter for session:sync events

Caution

TabSyncManager depends on BroadcastChannel. It does not currently provide a localStorage fallback, so older browsers should use a custom fallback if cross-tab sync is required.

Session Monitor

SessionMonitor implements the RP side of OIDC Session Management. It loads the OP’s check_session_iframe, polls it with the current session_state, and emits events when the OP reports that the session changed.

Usage

import { SessionMonitor } from '@authrim/web';

const monitor = new SessionMonitor({
  checkSessionIframeUrl: discovery.check_session_iframe,
  clientId: 'my-app',
  opOrigin: 'https://auth.example.com',
  pollInterval: 2000,
  maxErrors: 3,
});

const unsubscribe = monitor.on(async (event) => {
  if (event.type === 'session:changed') {
    await auth.signOut({ logoutScope: 'local' });
    window.location.href = '/login';
  }

  if (event.type === 'session:error') {
    console.warn('OIDC session check failed:', event.error);
  }
});

await monitor.start(initialSessionState);

// After a successful re-authentication, update the monitored session_state.
monitor.updateSessionState(newSessionState);

window.addEventListener('beforeunload', () => {
  monitor.stop();
  unsubscribe();
});

Parameters

Parameter	Type	Default	Description
checkSessionIframeUrl	string	-	OP check_session_iframe URL from discovery
clientId	string	-	OAuth client ID
opOrigin	string	-	Expected OP origin for postMessage validation
pollInterval	number	2000	Polling interval in milliseconds
maxErrors	number	3	Consecutive errors before the monitor stops

Event Types

Type	Meaning
session:changed	OP reports that the user session changed
session:unchanged	OP reports that the monitored session_state is still current
session:error	The iframe check failed or the OP returned error
session:stopped	Monitoring stopped manually or after too many errors

Front-Channel Logout

FrontChannelLogoutHandler validates OIDC front-channel logout requests delivered to your registered logout URI. The OP typically loads this URI in a hidden iframe with iss and optionally sid query parameters.

Browser Compatibility

Front-Channel Logout relies on iframe loading and local session cleanup. Browsers that restrict third-party cookies or iframe storage access can make this mechanism unreliable. For most browser apps, combine local logout, Tab Sync, and explicit app-session checks as the primary session management path.

Setup

Register a front-channel logout URI in the Authrim Admin panel:

Setting	Value
Front-Channel Logout URI	https://myapp.com/logout/front-channel
Front-Channel Logout Session Required	true when you can validate sid

Handler

import { FrontChannelLogoutHandler } from '@authrim/web';

const handler = new FrontChannelLogoutHandler({
  issuer: 'https://auth.example.com',
  sessionId: currentSessionId,
  requireIss: true,
  requireSid: true,
  onLogout: async (params) => {
    await auth.signOut({ logoutScope: 'local' });
    console.log('Front-channel logout handled:', params.sid);
  },
});

if (handler.isLogoutRequest()) {
  const result = await handler.handleCurrentUrl();

  if (!result.success) {
    console.warn('Invalid front-channel logout request:', result.error);
  }
}

Parameters

Parameter	Type	Default	Description
issuer	string	-	Expected OP issuer
sessionId	string	-	Current session ID for sid validation
requireIss	boolean	false	Require and validate the iss parameter
requireSid	boolean	false	Require and validate the sid parameter
onLogout	(params) => void | Promise<void>	-	Called after request validation succeeds

Check Session Iframe

CheckSessionIframeManager is the lower-level wrapper used by SessionMonitor. Use it directly when you want to control polling yourself.

Browser Compatibility

OIDC Check Session Iframe depends on third-party iframe behavior and may not work in Safari ITP or browsers that block third-party cookies. Treat it as an enterprise/OIDC compatibility feature, not the only logout detection mechanism.

Usage

import { CheckSessionIframeManager } from '@authrim/web';

const manager = new CheckSessionIframeManager({
  checkSessionIframeUrl: 'https://auth.example.com/check-session',
  clientId: 'my-app',
  opOrigin: 'https://auth.example.com',
  timeout: 5000,
});

await manager.initialize();

const result = await manager.checkSession(currentSessionState);

if (result.response === 'changed') {
  await auth.signOut({ logoutScope: 'local' });
  window.location.href = '/login';
}

manager.destroy();

Parameters

Parameter	Type	Default	Description
checkSessionIframeUrl	string	-	OP check_session_iframe URL
clientId	string	-	OAuth client ID
opOrigin	string	-	Expected OP origin for message validation
timeout	number	5000	Iframe load and message response timeout

Combining Monitors

A practical browser setup usually combines Tab Sync with one explicit session check path:

import { TabSyncManager } from '@authrim/web';

const tabSync = new TabSyncManager();
tabSync.initialize();

const stopLeader = tabSync.onLeaderChange((isLeader) => {
  if (!isLeader) return;

  const timer = window.setInterval(async () => {
    const isValid = await auth.session.validate();

    if (!isValid) {
      await auth.signOut({ logoutScope: 'local' });
      tabSync.broadcastLogout();
      window.location.href = '/login';
    }
  }, 60000);

  window.addEventListener('beforeunload', () => window.clearInterval(timer), {
    once: true,
  });
});

window.addEventListener('beforeunload', () => {
  stopLeader();
  tabSync.destroy();
});

Add SessionMonitor when your deployment exposes OIDC check_session_iframe and you need OP-session change detection in addition to app-session validation.

Next Steps

• Session Management - Basic session operations
• Events - SDK event system
• Cross-Domain SSO - SSO across multiple domains