Redirecting users from SSO error page when authentication is cancelled

Overview

In some deployments, users may cancel strong authentication (for example, in FTN) before the authentication actually starts. In this case, Ubisecure SSO shows its standard error page with a “Continue” link, where the target URL is derived from the original authorization request’s redirect_uri.

Some customers want to override this behavior and send the user to a different URL (e.g. a custom landing page or service-specific error page) when a specific error condition occurs.

This article describes how to implement such behavior using SSO login screen UI extension JavaScript.

Use case

SSO is used to proxy authentication from FTN. When the user cancels authentication:

FTN returns a failure to SSO.
SSO shows an error page with an error message and a “Continue” link.
Customer wants to redirect the user to a custom URL instead of using the “Continue” link’s default target, but only for this specific error condition.

In this case, the relevant error message text is (Finnish):

Tunnistautuminen keskeytyi

When this text appears on the SSO error page, the user should be redirected automatically to a configurable URL.

Approach

We use a small piece of custom JavaScript loaded via the SSO Login Screen UI Extension mechanism.

The script:

Checks that the current view is the SSO error page (error.jsp).
Looks for the error message element with ID loginerror.
If the text content contains the specific message Tunnistautuminen keskeytyi, performs a client-side redirect (window.location.href) to the desired URL.
If the condition is not met, the error page behaves as usual.

For general guidance on adding custom JavaScript to the SSO login/error pages, see:

SSO login screen UI extension examples
https://ubisecuredev.atlassian.net/wiki/spaces/KNB/pages/5426380729

Configuration steps

1. Determine the target URL

Decide where users should be redirected when they cancel authentication.
For example:

https://example.com/org/authentication-cancelled
A generic help or support page
A service-specific error page

In the example below, replace https://url with your actual target.

2. Create the UI extension JavaScript

Create a JavaScript file (for example error-redirect.js) with the following content:

$(document).ready(function() {
   // Ensure we are on the SSO error page
   if (view.getViewServerPage().endsWith('error.jsp') && document.getElementById("loginerror") != null) {
      var error_message = document.getElementById("loginerror");
      // Check for the specific error text returned when authentication is cancelled
      if (error_message.innerText.includes("Tunnistautuminen keskeytyi")) {
          // Redirect user to a custom URL
          window.location.href = "https://url";
      }
   }
});

Notes:

view.getViewServerPage().endsWith('error.jsp') is used to limit the behavior to the SSO error page.
#loginerror is the standard ID used for the error message container on that page.
The check uses includes("Tunnistautuminen keskeytyi") to match the Finnish message text returned in this particular case.

3. Deploy the JavaScript to SSO

Follow the standard SSO UI extension process (see: https://ubisecuredev.atlassian.net/wiki/spaces/KNB/pages/5426380729/SSO+login+screen+ui-extension+examples#SSOloginscreenui-extensionexamples-Step-by-step-guide )

Include the following line in the template configuration file
custom/templates/templatename.properties
javascript = /resource/script/error-redirect.js
copy error-redirect.js (created in step2 )in custom/resources/script directory
Add reference in custom/resource.index
error-redirect.js = resources/script/error-redirect.js
In Ubisecure SSO Management, add the template name to Agent being used.
Deploy the script and configuration to a test environment. Only after successful testing should the configuration be promoted to production.