Web SSO

Overview

Web Single Sign-On (SSO) is a browser-based authentication mechanism that enables users to access multiple web applications with a single login. This simplifies authentication, enhances security by reducing password fatigue, and improves user experience. LoginRadius Web SSO utilizes browser storage mechanisms, including sessionStorage, localStorage, and cookies, to manage user sessions across various applications. Authentication is centralized through the Hosted Page, which manages session sharing across authorized applications. With Web SSO, users logged into one application are automatically authenticated across other connected applications.

This document guides you through the Web SSO process, including configuration, implementation, and best practices for a secure and efficient authentication experience.

Common Use Cases of Web SSO

SaaS Platform Integration: A cloud-based project management tool allows enterprise clients to use Web SSO for their employees. When employees log in, they automatically gain access to integrated tools like document collaboration and time tracking without separate logins. This use case demonstrates how Web SSO can streamline the user experience in a business environment.
Enterprise Customer Portals: A B2B e-commerce platform enables customers to use Web SSO to seamlessly access order management, invoicing, and customer support dashboards under a single authentication flow.
Partner and Vendor Access Management: A multinational corporation provides Web SSO to its vendors and suppliers, allowing them to securely access supply chain management and invoicing portals without needing separate credentials for each service.

Web SSO Visual Flow

Below is the visual representation of web SSO:

WEB SSO

The following displays the sequence diagram of the Web SSO process:

WEB SSO

Configuration

To allow cross-domain AJAX calls, log in to the LoginRadius Admin Console and navigate to:
Tenant Settings> Configured Domains. Add the required domains to whitelist them for your application, ensuring seamless cross-domain authentication and API interactions.

Integration Guide

To understand the SSO deployment via LoginRadius JavaScript Libraries, refer to the following example:
You have two websites, Web Application A and Web Application B. You need to complete the following steps to allow the logged-in customers of Website A to be recognized on Website B (without explicitly logging in) and vice versa.

LoginRadius JavaScript Libraries inclusion and object initialization on Website A and B, respectively.
Implement the following actions on Web Application A:
a. ssoLogin: This action sets the SSO session on a centralized domain managed by LoginRadius (Hosted Page).
b. logout: This action logs the customer out of all the websites connected for SSO.
c. ssoNotLoginThenLogout: This action checks the active SSO session and verifies whether the customer is logged in on another website.
Implement the above actions on Web Application B as well.

Both web applications will communicate with the centralized domain managed by LoginRadius (hosted page) to check the access token for login and logout requests.

To complete these steps, refer to the detailed explanation of implementation using the LoginRadius v2JS library.

The following is the sequential execution of the above example:

Add the following script to the <head> section of your HTML file

<script src="https://auth.lrcontent.com/v2/js/LoginRadiusV2.js" type="text/javascript"></script>

Using the script from the LoginRadius CDN is recommended rather than making a local copy.

Add the following JavaScript code to initialize the LoginRadiusV2 object:

var commonOptions = {};
commonOptions.apiKey = "{your-loginradius-api-key}";
commonOptions.appName = "{LoginRadius-site-name}";
var LRObject = new LoginRadiusV2(commonOptions);

The actions below should be executed when the page loads. Use the ssoLogin action to initiate an SSO session. Add the following code to your Index.html file:

var ssologin_options= {};
ssologin_options.onSuccess = function(response) { 
   console.log(response); 
}; 
LRObject.util.ready(function() { 
   LRObject.init("ssoLogin", ssologin_options); 
}); 

var login_options = {}; 
login_options.onSuccess = function (response) { 
   
   console.log(response); 
}; 
login_options.onError = function (errors) { 
console.log(errors); 

}; 
login_options.container = "login-container"; 
LRObject.util.ready(function () { 
   LRObject.init("login", login_options); 

});

To handle logout and clear browser sessions, add the following code:

var logout_options = {}; 
logout_options.onSuccess = function() { 
   console.log("User logged out successfully."); 
}; 
LRObject.util.ready(function() { 
   
   LRObject.init("logout", logout_options); 
});

The ssoNotLoginThenLogout action verifies the presence of an active SSO session and logs the user out if none exists.

var check_options = {}; 
check_options.onError = function() { 
   console.log("User is not logged in."); 
};
check_options.onSuccess = function(response) { 
   console.log("Access token:", response); 
}; 
LRObject.util.ready(function() { 
   LRObject.init("ssoNotLoginThenLogout", check_options); 
});

Once an access token is obtained, use it to fetch the user profile from LoginRadius:

var xhr = new XMLHttpRequest();
var url = "https://api.loginradius.com/identity/v2/auth/account?apiKey=<API-KEY>&access_token=" + access_token;
xhr.open("GET", url);
xhr.setRequestHeader("X-Requested-With", "XMLHttpRequest");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
xhr.onreadystatechange = function() {
    if (xhr.readyState === 4) {
        console.log(xhr.response);
    }
};

SSO Token Setup Methods

Here is a comparison of the various methods used for Web SSO integration with LoginRadius:

AJAX Call
Custom Token Cookies
HTTPS Redirect

Makes an API request to set the SSO token via AJAX.

Use-case: Ideal for web applications that require real-time session updates.
Considerations: Requires cross-domain AJAX calls to be whitelisted.
Endpoint: https://<LoginRadius-Site-Name>.hub.loginradius.com/ssologin/setToken

Parameters Used:

token (Access token to be set for SSO) 
apikey (LoginRadius API Key)

Example code

$.ajax({
    type: "GET",
    url: "https://<LoginRadius-Site-Name>.hub.loginradius.com/ssologin/setToken",
    dataType: "json",
    data: $.param({
        token: "<your-access-token>",
        apikey: "your-API-key"
    }),
    xhrFields: {
        withCredentials: true
    },
    success: function(response) {
        console.log(response);
    },
    error: function(xhr, status, error) {
        console.log(error);
    }
});

Stores an access token as a cookie with a "remember me" option.

Use-case: Useful for applications that need persistent user sessions.
Considerations: Limited by browser cookie policies and expiration settings.
Endpoint: https://<LoginRadius-Site-Name>.hub.loginradius.com/ssologin/setcustomtoken

Parameters Used:

token (Access token to be set for SSO)
apikey (LoginRadius API Key) 
Isrememberme (true/false - determines if the token should persist)

Example code

  $.ajax({
    type: "GET",
    url: "https://<your-lr-app-name>.hub.loginradius.com/ssologin/setcustomtoken",
    dataType: "json",
    data: $.param({
        token: token,
        apikey: "your-API-key",
        Isrememberme: "true"
    }),
    xhrFields: {
        withCredentials: true
    },
    success: function (response) {
        console.log(response);
    },
    error: function (xhr, status, error) {
        console.log(error);
    }
});

Redirects users to an endpoint where the token is set in the browser.

Use-case: Suitable for Safari users where cross-domain cookies are restricted.
Considerations: Requires a callback URL for redirection after setting the token.
Endpoint: https://<LoginRadius-Site-Name>.hub.loginradius.com/ssologin/setSafariToken

Parameters Used:

token (Access token to be set for SSO) 
apikey (LoginRadius API Key) 
callback (URL to redirect users after setting the token)

Example code

if (safari) {
    window.location = "https://<LoginRadius-Site-Name>.hub.loginradius.com/ssologin/setSafariToken?token=<accesstoken>&callback=<callbackURL>";
} else {
    // Use AJAX call as shown in previous sections.
}

Best Practices for Web SSO Implementation

Implementing Single Sign-On (SSO) with LoginRadius enhances security and user convenience. To maximize its effectiveness, follow these best practices:

Use HTTPS for all authentication and token exchanges to prevent data interception.
Set token expiry and enable refresh tokens to maintain secure sessions.
Restrict token scope to grant only necessary permissions.
Provide clear login/logout options with visible authentication status.
Monitor and audit SSO activity to detect and mitigate security threats.