Share this post:
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.
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.
Authentication 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).
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.
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.
See the KC entry here for more information on the configuration steps for http-rsp-header setup.
Configure redirects to be handled in HTML
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 Management
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 implicit flow
The OAuth implicit flow returns tokens directly from the authorization request, making it an ideal 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.
When making the request for the token, an authenticated web session is required.
Collecting the OAUTH Token
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).
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:
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.
- 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 request 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.