ISAM and Single Paged (SPA) Applications

Share this post:

Updated: 13th May 2019 to discuss the content type aware responses in ISAM (9.0.6 release end of 2018)

We’ve been having some conversations recently about the best way to achieve an authentication solution when implementing a single paged (SPA) app. In this piece we’re going to cover several recommendations, best practices and tweaks which can be used to effectively maintain an authenticated user session while also dynamically loading content through AJAX and other requests – enforcing appropriate API authorization for security and user experience.

The IBM Verify Demo site uses principals from both SPAs and traditional web pages to create a dynamic user experience.

The IBM Verify Demo site uses principals from both SPAs and traditional web pages to create a dynamic user experience.

What is an SPA?

A single-page application (SPA) is a web application or web site that interacts with the user by dynamically rewriting the current page rather than loading entire new pages from a server. This approach avoids interruption of the user experience between successive pages, making the application behave more like a desktop application.

Source Wikipedia.

Essentially, an SPA is an application that operates using a combination of HTML, JavaScript and CSS, and is quite often built using a framework. Common frameworks include React and Angular.

SPA Request Flow

538478644Authentication and session management with an SPA

There are (at least) two schools of thought for authentication with an SPA, either using the existing Web Session via Cookies, or using an API approach using authentication tokens. When using an SPA with ISAM this typically translates into authentication with the standard ISAM Session cookie (PD_SESSION) or using OAUTH 2.0 Access tokens, or for other use cases JWTs.

Session Cookie Based Authenticated State Management

When using a Session Cookie in a browser, an SPA should require minimal changes to operate through ISAM – with the authenticated state being handled by the standard cookie jar. The only catch is handling the session timeout and other ISAM responses gracefully. Fortunately, there are a few handy settings to help you do this.

Initially an SPA may be loaded from either an authenticated or unauthenticated state – depending on your configured ACLs. If the SPA loads from an unauthenticated state, then it would be responsible for the initial authentication flow – presenting the login page of ISAM when authenticated resources are required (or it may also call the API Authsvc REST APIs from it’s own UI).

SPA Flow using ISAM Session Cookie

Know your Session timeout

– ISAM can be configured to return the remaining life of the session on every request, this means you can proactively warn a user before it’s too late.
See the the Knowledge Center (KC) entry here for more information on the [rsp-header-names] stanza.Read SPA session timeout from header

Identify a session timeout easily

ISAM can be configured to return the operation of a login event as a custom header. This means that you can easily look for a response header containing “login” when the session has expired.
Read SPA Login response from header
This significantly improves the ability to detect in JavaScript a timeout event.
See the KC entry here for more information on the configuration steps for http-rsp-header setup.

Note: From ISAM 9.0.6, for an even better approach, see “Content Type Aware Responses” below.

Content Type Aware responses

In ISAM (Late 2018 version) ISAM supports a range of content type aware responses. Essentially any error response that ISAM used to respond back in HTML can now be configured to respond with a JSON (or other data type) message. In addition to the content type, the HTTP error code can be configured, where a “Login prompt” can be configured to return a 401 for example.

The full documentation in the KC is detailed here.

The error messages in the ISAM management route, are patterned as follows:

<file identifier>{.<response_code>}.<mime sub-type>

Such that the standard login form might look like this:


whilst the JSON one might look like this:


This is very useful for SPA deployment, where you can configure the responses to a particular circumstance to suite the SPA/API client.

Configure redirects to be handled in responses

Rather than returning 302 redirects to the browser on ISAM operations, ISAM can be configured to return pages with JavaScript redirects. These can be easily parsed by JavaScript if necessary to extract critical information.
See the KC entry here for more information about the enable-html-redirect setting.

Disable session activity on certain URLs

Some SPAs make regular calls to URLs on your server, which may or may not be triggered by user activity. If you want to avoid certain requests from triggering the ‘activity’ mechanism, and keeping the session alive, you can do that through configuration.
See the KC entry here for more information about the preserve-inactivity-timeout setting.

Token Based Authenticated State Management846011382

Under some circumstances and for some clients, operating with an authentication token can be desirable. SPAs operating on mobile devices in hybrid applications is one particularly common place, or applications where the server that hosts the SPA is not the same server that hosts the active/dynamic content. This guide will focus on the use of OAuth 2.0 based Access Tokens, typically with a fairly short lifetime and using ISAM’s OAUTH-Auth capabilities. If you’re looking for more detail on JWT as a form of Access Token, Leo has done an indepth technical article on the topic here.

Up front there are two main architectures you can choose:

  • Host the Web Content and the API Content behind the same ISAM Reverse Proxy
  • Host the Web Content and the API Content behind different ISAM Reverse Proxies
    (This is also relevant when using another API gateway for the API content – e.g. DataPower, API Connect, or 3rd Party API Gateways like Mulesoft, Axway, APIGEE).

In general, when actively using different authentication mechanisms for your API requests (token AND cookie for example), there are benefits to hosting two separate Reverse Proxies. This allows for more customisation on the responses you return to the different calling clients. In either case however – many of the suggestions above for a cookie based approach can still be useful for identifying and handling session timeouts and error events.

Deploying OAuth in this context is quite different to the traditional 3-legged-OAUTH flow, because the OAUTH client is now the same entity as the user-agent, and the authorization server can be the same entity as the resource server. The client is considered a ‘public’ client, as such there is no client secret defined, and typically there is no refresh token issued – which is why session management is important to handle properly to reduce the friction on the users experience.

Use the OAuth/OIDC implicit and or authorization code flows

The OAuth implicit flow returns tokens directly from the authorization request, making it the historical method for an in the browser OAUTH client to get bearer tokens to use to for accessing APIs. Using the implicit flow over the more traditional authorization code flow saves the number of browser to server round trips necessary to acquire access tokens, it also avoids providing unauthenticated access to the /token endpoint. It does however have other security concerns around token leakage. That discussion continues to evolve, and we won’t go into detail here.

(For more information, one simply need to google “oauth implicit vs authorization code” to get into the discussion. )

The good news, ISAM supports both (and in fact all major OAuth/OIDC flows including PKCE support) so many of the patterns still apply, and where they don’t – they suggest an alternative with the use of session based authentication – see Cookie based approach above.

When making the request for the token, an authenticated web session is required, or the user directed to login.

SPA OAuth Based Session flow

Collecting the OAUTH Token

The OAuth implicit flow by default results in a 302 to the OAUTH clients provided redirect URI, with the access token supplied in the URL as a fragment. Since 302s can be cumbersome to handle via XHR, ISAM can be configured to instead use response_mode=form post an OpenID Connect extension which returns the values in a form, which can be much more easily consumed via JavaScript.

Separate browser and API reverse proxies

By using separate WebSEAL instances for browser and API access OAuth allows granular control over API and browser access methods. Use forms, EAI or ISAM AAC Authentication service based methods for authentication on the web channel and exclusively use OAUTH-auth on the ISAM that services the API channel. This enables ISAM to more appropriately respond to authentication challenges suiting the client requests.

Where this isn’t possible, you can make use of the header recommendation, looking for the operation in the header when ISAM presents an error state (See Identify a Session Timeout above).

Note: With the addition of content-type aware responses in ISAM 9.0.6, the benefits of separation are reduced.

Cloud Deployment of Applications

The SPA can be hosted on various infrastructure, and may not necessarily be hosted behind ISAM. For example the application might be hosted on AWS, making use of an ISAM hosted on-premise or in another enterprise controlled data center. An example of this is shown below:

SPA hosted in Cloud

Handling Token Expiry Intelligently

When a token is received, you can capture the token expiry period. Keeping track of this timeout in your SPA allows you to preemptively handle a timeout gracefully, before API requests are rejected.


You might also consider ‘introspecting’ the token where the session state is unknown to determine its validity.

Another useful tactic when using in conjunction with a Identity Provider/Authorization Server, is to ensure inactivity on the web session doesn’t break your user experience. Use short lived access tokens within your SPA, requiring a new token before your web session expires, which will prevent unexpected prompts for authentication with continued use.

For example, if your ISAM web session inactivity timeout was 25 minutes, you might set your AT expiry to 10 minutes, resulting in a ‘ping’ back to the web session ensuring that continued use of the SPA also maintains the traditional web session/experience.


Enable your developers to request their own credentials

Take the burden off the system administrators, provide a developer portal to get OAUTH credentials directly from ISAM. See this article here for more information.

image (4)

Resource Servers

In many of the diagrams above, we make use of ISAM as the Reverse Proxy protecting the resource server, but this is by no means critical to the deployment. Being based around Open standards of OIDC and OAuth 2.0 it’s easy to use many other enforcement points or API gateways with ISAM. There are also patterns where the tokens may be opaque or JWT based, or a combination of both.

Common patterns are found with API Connect, DataPower, Mulesoft, Apigee etc. Using the flexibility and dynamic authentication capabilities of ISAM in conjunction with the API Gateways capabilities to get the best of both worlds.

Where the token is not JWT based, the pattern can be consumed via token introspection at the gateway, and Leo has prepared a great technical article here:

Introspection with ISAM

Using ISAM as the Authorization Server, and an alternative API gateway

Other Notes:

  • API driven authentication can be easily run through ISAMs AAC API Authentication Service. You’re not constrained to the traditional HTML Login forms. Every mechanism in AAC can be made via REST API calls allowing the SPA developer to own the UX.
  • Cloud Identity, the IBM IdAAS can also be used for application authentication, with it’s native OpenID Connect Support.
  • SPAs can be configured to act as an ISAM EAI – External Authentication Interface, just like any other web application. The special trick is that EAI headers should be added to the final REST response in the authentication flow. That same REST API URL  should be configured as the trigger URL.
  • ISAMs Context Based Access can be configured to extract JSON attributes from the request for authorization scenarios in the [azn-decision-info] stanza of the Reverse Proxy.

Click here to rate this article

Rate this article :

Technical Offering Manager - Access and Cloud Identity


Software Engineer - IBM Security Access Manager

More Articles stories
By Carsten Hagemann on June 20, 2022

Getting started with the IBM Verify SDK

The IBM Verify SDK is a library available for Android and iOS and provide classes to create rich native client mobile applications that interact with IBM Cloud Identity and IBM Security Access Manager, so that enterprises can easily integrate flexible and intelligent multi-factor authentication into their applications. Multi-factor authentiation (MFA) verifies an indiviual’s identity by […]

Continue reading

By Martin Schmidt on July 11, 2019

Modernizing your B2C Portal Security – LDAP Proxy Deep Dive

In this part of our series we are taking a deeper look on how the LDAP reverse proxy works and what is needed to be done to make it work. Enable CI In this part we look at what needs to be done on the CI side and what information needs to be collected. We […]

Continue reading

By Martin Schmidt on May 4, 2019

Modernizing your B2C Portal Security – Desired End State

Proposition: As we have seen in part one of this series, managing customer identities for a portal can be a challenge and distraction for the business.  In this part of the series we will outline how a modernized solution for a portal security can simplify operations and free your team up to focus on the […]

Continue reading