SSO-Manager

51 min

SSO Manager Documentation

Overview

The SSO Manager provides a unified authentication flow for both web and native app platforms. It handles OAuth and token-based authentication with external SSO providers, supporting multiple trigger mechanisms including URL parameters and postMessage communication.

Singleton Pattern: The SSOManager class is a singleton, ensuring only one authentication instance exists throughout the application lifecycle.

Key Features

Dual Platform Support: Works seamlessly on both web and native apps

Multiple Trigger Methods: URL parameters, postMessage (iframe integration)

Automatic State Detection: Determines login/logout requirements based on SSO provider responses

Configurable: Highly customizable through a central configuration file

Return URL Handling: Automatically manages return navigation after authentication

Singleton Architecture: Built-in singleton pattern ensures consistent state management

File Structure

default/storefront/assets/scripts/custom/ ├── custom.js # Main entry point - import init.js here └── sso-manager/ ├── config.js # Configuration file ├── sso-manager.js # Core SSOManager class └── init.js # Extended class with lifecycle hooks

Installation & Setup

1. Import in custom.js

Add the import to your main custom.js file:

File: default/storefront/assets/scripts/custom/custom.js

import './sso-manager/init.js';

This will automatically initialize the SSO Manager when Purple Service is ready.

2. Access the SSO Manager

// Import the singleton instance (from anywhere in your code) import { ssoManager } from './sso-manager/init.js'; // Wait for initialization, then use ssoManager.login(); // You can also use the base class directly if needed import { SSOManager } from './sso-manager/sso-manager.js'; const instance = SSOManager.getInstance();

Important: Due to the singleton pattern, multiple instantiations return the same instance:

import { SSOManager } from './sso-manager/sso-manager.js'; const instance1 = new SSOManager(); const instance2 = new SSOManager(); const instance3 = SSOManager.getInstance(); console.log(instance1 === instance2 === instance3); // true

3. Configure

Edit config.js to match your environment:

File: default/storefront/assets/scripts/custom/sso-manager/config.js

export const config = { type: "oAuth", withPostMessage: false, externalState: { login: ["logged_in", "true"], logout: ["logged_in", "false"], purchase: ["purchase", "true"], token: ["transferToken"] }, urlParamKeys: { returnUrl: "returnTo", loginViaUrl: "external_login", checkoutViaUrl: "external_checkout", logoutViaUrl: "external_logout", }, postMessage: { validOrigins: [ "https://dev.hz.de", "https://web.purplemanager.com/heidenheimer-staging", "resource://dynamic", ], }, targetUrlParams: {}, returnUrlParams: {}, removeUrlParams: ["jwt"], loginUrl: "https://checkout-stage.hz.de/dispatch", logoutUrl: "https://checkout-stage.hz.de/logout", checkoutUrl: "https://checkout-stage.hz.de/start", };

Configuration Reference

Core Settings

type

Type: 'oAuth' | 'transferToken' Description: Specifies which SSO procedure is active. Example: "oAuth"

withPostMessage

Type: boolean Description: Enable triggering login/logout via postMessage for iframe integration. Default: false

External State Configuration

The externalState object defines URL parameters that indicate authentication state from the SSO provider.

Structure

Each state is defined as an array: [urlParameterKey, expectedValue?]

If expectedValue is provided, the parameter value must match exactly

If expectedValue is omitted, any value for that parameter is considered valid

externalState.login

Type: [string, string?] Description: Indicates external login state Example: ["logged_in", "true"] - Checks if URL has ?logged_in=true

externalState.logout

Type: [string, string?] Description: Indicates external logout state Example: ["logged_in", "false"] - Checks if URL has ?logged_in=false

externalState.purchase

Type: [string, string?] Description: Indicates external purchase action completed Example: ["purchase", "true"] - Checks if URL has ?purchase=true

externalState.token

Type: [string, string?] Description: TransferToken parameter, usually declared without expected value Example: ["transferToken"] - Checks if URL has ?transferToken=<any_value>

URL Parameter Keys

Defines the URL parameter names used to trigger and handle authentication flows.

urlParamKeys.returnUrl

Type: string Description: URL parameter name under which the external API expects the return URL Example: "returnTo" - Results in ?returnTo=https://yoursite.com

urlParamKeys.loginViaUrl

Type: string Description: URL parameter which triggers login. Can receive a string value to use as targetUrl Example: "external_login" - Trigger with ?external_login or ?external_login=https://custom-sso.com

urlParamKeys.checkoutViaUrl

Type: string Description: URL parameter which triggers checkout. Can receive a string value to use as targetUrl Example: "external_checkout" - Trigger with ?external_checkout or ?external_checkout=https://custom-checkout.com

urlParamKeys.logoutViaUrl

Type: string Description: URL parameter which triggers logout Example: "external_logout" - Trigger with ?external_logout

PostMessage Configuration

postMessage.validOrigins

Type: string[] Description: Array of origins allowed to trigger SSO Manager login/logout via postMessage Security: Only messages from these origins will be processed Example:

validOrigins: [ "https://dev.hz.de", "https://web.purplemanager.com/heidenheimer-staging", "resource://dynamic" // Non-standard protocol support ]

Additional URL Parameters

targetUrlParams

Type: Record<string, string | number | boolean> Description: Additional parameters to add to the target SSO URL Example:

targetUrlParams: { client_id: "your-client-id", response_type: "token" }

returnUrlParams

Type: Record<string, string | number | boolean> Description: Additional parameters to add to the return URL Example:

returnUrlParams: { source: "external_auth", timestamp: Date.now() }

removeUrlParams

Type: string[] Description: URL parameters to remove upon login/logout to avoid endless loops or expose sensitive data Example:

removeUrlParams: ["jwt", "session_id", "temp_token"]

SSO Endpoint URLs

loginUrl

Type: string Description: URL to be called for external login when none is provided in the login call Example: "https://checkout-stage.hz.de/dispatch"

logoutUrl

Type: string Description: URL to be called for logout (always used internally) Example: "https://checkout-stage.hz.de/logout"

checkoutUrl

Type: string Description: URL to be called for external checkout when none is provided in the checkout call Example: "https://checkout-stage.hz.de/start"

Configuration Examples

Basic OAuth Configuration

Configuration with PostMessage Support

export const config = { type: "oAuth", withPostMessage: true, // Enable postMessage externalState: { login: ["auth_status", "authenticated"], logout: ["auth_status", "logged_out"], token: ["access_token"] }, urlParamKeys: { returnUrl: "callback", loginViaUrl: "sso_login", checkoutViaUrl: "sso_checkout", logoutViaUrl: "sso_logout", }, postMessage: { validOrigins: [ "https://paywall.example.com", "https://iframe-app.example.com" ] }, targetUrlParams: { client_id: "abc123", scope: "read write" }, returnUrlParams: { source: "sso_return" }, removeUrlParams: ["temp_token", "session"], loginUrl: "https://auth.example.com/oauth/login", logoutUrl: "https://auth.example.com/oauth/logout", checkoutUrl: "https://auth.example.com/subscribe", };

Transfer Token Configuration

export const config = { type: "transferToken", withPostMessage: false, externalState: { login: ["status"], // Any value accepted logout: ["status"], // Any value accepted token: ["token"] // Token key without specific value check }, urlParamKeys: { returnUrl: "return_url", loginViaUrl: "auth_login", checkoutViaUrl: "auth_checkout", logoutViaUrl: "auth_logout", }, removeUrlParams: ["token", "status"], // Clean sensitive data loginUrl: "https://auth.example.com/token-login", logoutUrl: "https://auth.example.com/token-logout", checkoutUrl: "https://auth.example.com/token-checkout", };

Usage Examples

Basic login (uses default loginUrl):

https://www.hz.de?external_login

Login with custom SSO URL:

https://www.hz.de?external_login=https://custom-sso.com/login

Login from a specific page:

https://www.hz.de/premium-article?external_login

After authentication, user returns to /premium-article.

2. Trigger Checkout via URL

Basic checkout:

https://www.hz.de?external_checkout

Checkout with custom URL:

https://www.hz.de?external_checkout=https://custom-checkout.com/subscribe

3. Trigger Logout via URL

https://www.hz.de?external_logout

4. Programmatic Login/Logout

// Simple login ssoManager.login(); // Login with custom URL ssoManager.login('https://custom-sso.com/login'); // Login with options ssoManager.login('https://sso.com/login', { params: [ ['promo', 'summer2024'], ['source', 'email'] ], returnUrl: 'https://www.hz.de/thank-you' }); // Checkout ssoManager.checkout(); ssoManager.checkout('https://custom-checkout.com'); // Logout ssoManager.logout();

5. PostMessage Integration (for iframes)

Enable in config:

withPostMessage: true, postMessage: { validOrigins: [ "https://paywall-iframe.com" ] }

From iframe:

// Trigger login window.parent.postMessage({ method: 'login', targetUrl: 'https://sso.com/login' // optional }, '*'); // Trigger checkout window.parent.postMessage({ method: 'checkout', targetUrl: 'https://checkout.com/start' // optional }, '*'); // Trigger logout window.parent.postMessage({ method: 'logout' }, '*');

Authentication Flow

Web Platform Flow

1. User clicks login link └─> https://www.hz.de/article?external_login 2. Script redirects to SSO └─> https://sso.example.com/login?returnTo=https://www.hz.de/article 3. User authenticates on SSO provider 4. SSO redirects back with auth params └─> https://www.hz.de/article?transferToken=abc123&logged_in=true 5. Script processes authentication ├─> Validates token parameter ├─> Calls purple.entitlement.login() └─> Cleans URL: https://www.hz.de/article 6. Page reloads with user logged in

App Platform Flow

1. User triggers login from app 2. Script calls purple.app.performAuthentication() └─> Native app handles OAuth in system browser 3. App receives auth callback 4. Script processes returned data ├─> Validates authentication state └─> Calls purple.entitlement.login() 5. App refreshes with user logged in

Advanced Configuration

Singleton Pattern

The SSOManager class uses a built-in singleton pattern. When you extend this class, the singleton behavior is automatically inherited:

// All of these return the SAME instance const instance1 = new SSOManager(); const instance2 = new SSOManager(); const instance3 = SSOManager.getInstance(); console.log(instance1 === instance2 === instance3); // true

When you extend the class in init.js, the extended class automatically inherits the singleton pattern:

class ExtendedSSOManager extends SSOManager { // Your custom implementation } const ext1 = new ExtendedSSOManager(); const ext2 = new ExtendedSSOManager(); console.log(ext1 === ext2); // true - singleton works!

For Testing:

import { SSOManager } from './sso-manager/sso-manager.js'; // Reset the singleton between tests beforeEach(() => { SSOManager.resetInstance(); }); it('should initialize properly', () => { const instance = new SSOManager(); expect(instance).toBeDefined(); });

Custom Lifecycle Hooks

Extend the class in init.js to add custom behavior. The singleton pattern is automatically inherited - no extra work needed:

File: default/storefront/assets/scripts/custom/sso-manager/init.js

import { SSOManager } from './sso-manager'; import { extendStorefrontHook } from "../../utils/extend-storefront-hook"; class CustomSSOManager extends SSOManager { onLogin = { app: async () => { // Track login analytics analytics.track('user_logged_in', { platform: 'app' }); // Clear local cache await clearCache(); }, web: async () => { // Track login analytics analytics.track('user_logged_in', { platform: 'web' }); // Update UI updateUserInterface(); } } onLogout = { app: async () => { // Clear user data await clearUserData(); }, web: async () => { // Reset session sessionStorage.clear(); } } } // Automatic initialization via hook export let ssoManager = null; extendStorefrontHook('onPurpleServiceInit', () => { if (!ssoManager) { ssoManager = new CustomSSOManager(); } });

That's it! The singleton pattern is inherited from the parent class, and initialization happens automatically when Purple Service initializes.

Adding Parameters to Target URL

targetUrlParams: { client_id: "your-client-id", response_type: "token", scope: "read write" }

Result: SSO URL will include these params automatically.

Adding Parameters to Return URL

returnUrlParams: { source: "external_auth", timestamp: Date.now() }

Result: Return URL will include these params.

Removing Sensitive Parameters

removeUrlParams: [ "jwt", "session_id", "temp_token" ]

These parameters are removed after authentication to keep URLs clean.

API Reference

Singleton Methods

SSOManager.getInstance()

Get the singleton instance. Creates a new instance if none exists.

Returns: SSOManager - The singleton instance

Example:

import { SSOManager } from './sso-manager/sso-manager.js'; const auth = SSOManager.getInstance(); auth.login();

SSOManager.resetInstance()

Reset the singleton instance. Useful for testing or reinitialization.

Returns: void

Example:

import { SSOManager } from './sso-manager/sso-manager.js'; // For testing purposes SSOManager.resetInstance(); const newInstance = new SSOManager();

Initialization Functions

The SSO Manager uses automatic initialization via Purple Service hooks:

// In custom.js - import to activate import './sso-manager/init.js'; // In init.js - automatic initialization import { ssoManager } from './sso-manager/init.js'; extendStorefrontHook('onPurpleServiceInit', () => { if (!ssoManager) { ssoManager = new ExtendedSSOManager(); } });

No manual initialization required - the singleton is created automatically when Purple Service initializes.

Direct Access

If you need to access the singleton directly without waiting for the hook:

import { SSOManager } from './sso-manager/sso-manager.js'; const instance = SSOManager.getInstance();

Public Methods

Trigger the login flow.

Parameters:

targetUrl (string, optional): SSO login URL. Uses config.loginUrl if omitted.

options (object, optional):

params (array): Additional URL parameters as [key, value] pairs

returnUrl (string): Custom return URL for this login

Example:

ssoManager.login('https://sso.com/login', { params: [['promo', 'welcome']], returnUrl: 'https://www.hz.de/success' });

checkout(targetUrl?, options?)

Trigger the checkout flow. Same signature as login().

Example:

ssoManager.checkout('https://checkout.com/start');

logout()

Trigger the logout flow.

Example:

ssoManager.logout();

Public Properties

config

Access the configuration object.

console.log(ssoManager.config.loginUrl); ssoManager.config.loginUrl = 'https://new-sso.com/login';

isWeb

Boolean indicating if running on web platform.

if (ssoManager.isWeb) { console.log('Running on web'); }

utils

Utility functions for URL handling.

// Clear URL parameters ssoManager.utils.clearUrlParams(); // Get return URL const returnUrl = ssoManager.utils.getReturnUrl(); // Get stripped URL (without auth params) const cleanUrl = ssoManager.utils.getStrippedUrl();

Troubleshooting

Problem: Configuration changes don't take effect.

Solution: The singleton instance is created with the initial configuration. To change configuration:

import { SSOManager } from './sso-manager/sso-manager.js'; // Option 1: Reset and recreate SSOManager.resetInstance(); const newInstance = new SSOManager(); // Option 2: Modify existing instance config (runtime changes) const instance = SSOManager.getInstance(); instance.config.loginUrl = 'https://new-url.com';

Problem: Different parts of the app have different authentication states.

Solution: This shouldn't happen with the singleton pattern. If it does, verify that:

You're not accidentally calling resetInstance() somewhere

All parts of your app import from the same module path

No bundler/module issues are creating duplicate instances

All instantiations should go through the same singleton.

Problem: Clicking login link doesn't redirect to SSO.

Solutions:

Check if loginUrl is set in config

Verify URL parameter matches loginViaUrl in config

Check browser console for errors

Infinite Redirect Loop

Problem: Page keeps redirecting to SSO and back.

Solutions:

Verify externalState configuration matches SSO parameters

Add problematic parameters to removeUrlParams array

Check that SSO is sending expected parameter names/values

PostMessage Not Working

Problem: iframe postMessage doesn't trigger login.

Solutions:

Enable postMessage: withPostMessage: true

Add iframe origin to validOrigins array

Check browser console for origin validation errors

For non-standard protocols (resource://), ensure URL format is correct

Return URL Issues

Problem: User returns to wrong page after authentication.

Solutions:

Check returnUrl parameter name matches SSO expectation

Verify urlParamKeys.returnUrl is configured correctly

Use custom return URL in login options if needed

App Authentication Fails

Problem: Authentication doesn't work in native app.

Solutions:

Verify purple.app.performAuthentication is available

Check callbackParamName matches app configuration

Ensure app has proper URL scheme registration

Security Considerations

PostMessage Origin Validation

Always specify exact origins in validOrigins:

postMessage: { validOrigins: [ "https://trusted-iframe.com", "https://paywall.example.com" ] }

Never use wildcards in production!

Token Handling

Tokens are passed via URL parameters and immediately processed

URLs are cleaned after token extraction using removeUrlParams

Tokens should be short-lived (< 5 minutes)

HTTPS Only

Always use HTTPS URLs for SSO endpoints in production:

loginUrl: "https://sso.example.com/login" // ✅ Good loginUrl: "http://sso.example.com/login" // ❌ Bad

Browser Support

Modern Browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

Mobile: iOS Safari 14+, Chrome Mobile 90+

Required APIs:

URL / URLSearchParams

window.history.replaceState

window.addEventListener (postMessage)

Promises / async-await

Support

For issues or questions:

Check console logs (debug level)

Verify configuration matches SSO provider requirements

Review authentication flow in Network tab

Contact your SSO provider for server-side issues

SSO-Manager

SSO Manager Documentation

Overview

Key Features

File Structure

Installation & Setup

1. Import in custom.js

2. Access the SSO Manager

3. Configure

Configuration Reference

Core Settings

External State Configuration

URL Parameter Keys

PostMessage Configuration

Additional URL Parameters

SSO Endpoint URLs

Configuration Examples

Basic OAuth Configuration

Configuration with PostMessage Support

Transfer Token Configuration

Usage Examples

1. Trigger Login via URL

2. Trigger Checkout via URL

3. Trigger Logout via URL

4. Programmatic Login/Logout

5. PostMessage Integration (for iframes)

Authentication Flow

Web Platform Flow

App Platform Flow

Advanced Configuration

Singleton Pattern

Custom Lifecycle Hooks

Adding Parameters to Target URL

Adding Parameters to Return URL

Removing Sensitive Parameters

API Reference

Singleton Methods

Initialization Functions

Public Methods

Public Properties

Troubleshooting

Singleton-Related Issues

Login Not Triggered

Infinite Redirect Loop

PostMessage Not Working

Return URL Issues

App Authentication Fails

Security Considerations

PostMessage Origin Validation

Token Handling

HTTPS Only

Browser Support

Support