Session Monitoring

Overview

For applications that need to react to session changes in real time — such as logging out when the IdP session ends, or synchronizing auth state across browser tabs — @authrim/web provides several monitoring mechanisms.

Feature	Purpose	Browser Support
Tab Sync	Synchronize auth state across browser tabs	All modern browsers
Session Monitor	Periodic session validation polling	All browsers
Front-Channel Logout	Receive logout notifications via iframe	Limited (see note)
Check Session Iframe	Detect IdP session changes via postMessage	Limited (see note)

Tab Sync

Tab Sync synchronizes authentication state across browser tabs using the BroadcastChannel API. When a user logs in or out in one tab, all other tabs update their state.

Usage

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

const tabSync = new TabSyncManager({
  channelName: 'authrim-sync',  // default
  onLogin: (payload) => {
    console.log('Logged in (from another tab):', payload.user);
    // Update UI to show authenticated state
    refreshPage();
  },
  onLogout: () => {
    console.log('Logged out (from another tab)');
    // Clear UI and show login
    window.location.href = '/login';
  },
});

// Start listening
tabSync.start();

// Broadcast events (called automatically by SDK when auth state changes)
tabSync.broadcastLogin({ user, session });
tabSync.broadcastLogout();

// Stop listening
tabSync.stop();

How It Works

sequenceDiagram
    participant Tab1 as Tab 1
    participant BC as BroadcastChannel
    participant Tab2 as Tab 2
    participant Tab3 as Tab 3

    Tab1->>BC: broadcastLogin({ user, session })
    BC->>Tab2: onLogin({ user, session })
    BC->>Tab3: onLogin({ user, session })
    Tab2->>Tab2: Update UI
    Tab3->>Tab3: Update UI

Parameters

Parameter	Type	Default	Description
channelName	string	'authrim-sync'	BroadcastChannel name
onLogin	(payload) => void	—	Callback when login detected in another tab
onLogout	() => void	—	Callback when logout detected in another tab

Note

BroadcastChannel is supported in all modern browsers. For older browsers, the SDK falls back to localStorage events.

Session Monitor

The Session Monitor validates the session against the Authrim server at regular intervals. Unlike Check Session Iframe (which checks IdP-level session state), this validates the app-level session.

Usage

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

const monitor = new SessionMonitor({
  auth,  // Authrim client instance
  interval: 60000,  // Check every 60 seconds
  onExpired: () => {
    console.log('Session expired');
    window.location.href = '/login';
  },
  onError: (error) => {
    console.warn('Session check failed:', error);
  },
});

// Start monitoring
monitor.start();

// Stop monitoring
monitor.stop();

Parameters

Parameter	Type	Default	Description
auth	Authrim	—	SDK client instance
interval	number	60000	Polling interval in milliseconds
onExpired	() => void	—	Callback when session is no longer valid
onError	(error) => void	—	Callback on check failure

Front-Channel Logout

Front-Channel Logout allows the IdP to notify your application when the user logs out. The IdP loads a hidden iframe pointing to your app’s logout endpoint, which clears the local session.

Browser Compatibility

Front-Channel Logout relies on the IdP loading a hidden iframe to notify your application. In browsers that restrict third-party cookies or iframe storage access (Safari ITP, Chrome with third-party cookie restrictions), this mechanism may not function reliably. For most applications, Tab Sync combined with Session Monitor provides more reliable session management.

Setup

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

Setting	Value
Front-Channel Logout URI	https://myapp.com/logout
Front-Channel Logout Session Required	true (recommended)

Handler

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

const handler = new FrontChannelLogoutHandler({
  auth,  // Authrim client instance
  onLogout: () => {
    console.log('Logged out by IdP');
    window.location.href = '/';
  },
});

// Initialize (listens for logout iframe loads)
handler.init();

How It Works

1. User logs out at the IdP (or in another application)
2. IdP sends a GET request to your front-channel logout URI (in a hidden iframe)
3. Your page’s FrontChannelLogoutHandler receives the notification
4. Local session is cleared and onLogout callback is invoked

Check Session Iframe

The Check Session Iframe detects when the user’s IdP session changes (e.g., the user logged out in another app, or the session expired at the IdP).

It works by loading a hidden iframe from the IdP’s check_session_iframe endpoint and exchanging messages via postMessage.

Browser Compatibility

Check Session Iframe is based on the OIDC Session Management specification but does not work in Safari (ITP) or browsers that block third-party cookies. For most applications, use Session Monitor (polling) combined with Tab Sync instead. This feature is primarily useful for OIDC-compliant enterprise deployments where browser restrictions are controlled.

How It Works

sequenceDiagram
    participant App as Your App
    participant Iframe as Check Session Iframe
    participant IdP as Authrim IdP

    App->>Iframe: Start monitoring
    loop Every N seconds
        Iframe->>IdP: postMessage(client_id + session_state)
        IdP-->>Iframe: "changed" | "unchanged"
        alt Session changed
            Iframe->>App: Callback: session changed
            App->>App: Re-authenticate or logout
        end
    end

Usage

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

const manager = new CheckSessionIframeManager({
  clientId: 'my-app',
  checkSessionIframeUri: 'https://auth.example.com/check-session',
  interval: 5000,  // Check every 5 seconds (default: 3000)
});

// Start monitoring
manager.start({
  sessionState: currentSessionState,
  onChanged: () => {
    console.log('IdP session changed — re-authenticating...');
    // Try silent auth or redirect to login
  },
});

// Stop monitoring (e.g., on page unmount)
manager.stop();

Parameters

Parameter	Type	Default	Description
clientId	string	—	OAuth client ID
checkSessionIframeUri	string	—	IdP’s check_session_iframe URL
interval	number	3000	Polling interval in milliseconds

Combining Monitors

For a robust production setup, combine Tab Sync and Session Monitor:

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  enableOAuth: true,
});

// 1. Tab Sync — immediate cross-tab updates
const tabSync = new TabSyncManager({
  onLogin: () => location.reload(),
  onLogout: () => { window.location.href = '/login'; },
});
tabSync.start();

// 2. Session Monitor — periodic server-side validation
const monitor = new SessionMonitor({
  auth,
  interval: 60000,
  onExpired: () => { window.location.href = '/login'; },
});
monitor.start();

// Clean up on page unload
window.addEventListener('beforeunload', () => {
  tabSync.stop();
  monitor.stop();
});

Next Steps

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