How to Set Up Single Sign-On (SSO) for External or Third-Party Applications in uKnowva HRMS?

  • Print
15 Dec 2014
SSO & Authentication
Written by uKnowva Team
13106
0

Introduction

Single Sign-On (SSO) allows users to access a linked external or third-party application through uKnowva HRMS without having to log in to the external application separately. When a user opens the linked application through uKnowva HRMS, uKnowva passes the information required by the external application to identify and verify the user's active session.

For SSO to work securely, the external application must verify the session information received from uKnowva before logging the user into the application. uKnowva uses the ntk value as a unique identifier for the user's current session. The external application reads this value from the request and sends it to the uKnowva session verification service.

This article explains how to set up SSO for an external or third-party application, read the ntk session identifier, authorize the session verification request using the Bearer token, call the uKnowva session verification service, and use the response to log the user into the external application.

Prerequisite: Link the External Application

Before configuring the SSO flow, you must first link the external or third-party application with uKnowva HRMS.

If you have not linked the application yet, complete the application-linking process by following: Linking a Third-Party Application article before proceeding with the steps in this article.

Once the application has been linked, you need to make the required changes in the external application's code to handle the SSO request and verify the user's uKnowva session.

Step 1: Read the ntk Session Identifier from the Request

uKnowva calls the linked external application within an iframe and passes the encrypted session token in the URL using the ntk parameter. The ntk value uniquely identifies the user's current uKnowva session.

The ntk value is a random string that uniquely identifies the user's current uKnowva session. Your external application must read this value from the request so that it can send it to uKnowva for session verification.

The request will follow a structure similar to:

https://1.2.3.4/?ntk=[uknowva_session_token]

Here, [uknowva_session_token] represents the session-specific ntk value passed by uKnowva.

For example, in PHP, you can read the value using:

$uknowva_session_token = $_GET['ntk'];

In C#.NET, you can read it using:

uknowva_session_token = Request.QueryString("ntk");

In JSP, you can read it using:

uknowva_session_token = request.getParameter("ntk");

The external application should retrieve the ntk value from the request before proceeding with session verification.

Step 2: Send the Bearer Token in the Request Header

When calling the uKnowva session verification service, send the Bearer token in the request header for authorization.

The ntk session token and the Bearer token are sent separately. The ntk is passed in the request URL, while the Bearer token is sent in the request header.

For information on how to generate and use the Bearer token, refer to theAPI Authentication documentation.

Step 3: Call the uKnowva Session Verification Service

After obtaining the ntk value and preparing the authorized request, call the uKnowva session verification service.

The service uses the following URL structure:

https://[uknowva.instance.url]/index.php?option=com_custom&cmd=checksessiontoken&ntk=[uknowva_session_token]

Replace [uknowva.instance.url] with the URL of your uKnowva HRMS instance and [uknowva_session_token] with the ntk value received in the request.

The external application should not treat the ntk value alone as sufficient authorization for the request. It must complete both the request authorization and session verification before logging the user into the external application.

Step 4: Process the Session Verification Response

After the external application calls the uKnowva session verification service, uKnowva returns a JSON response containing the result of the session verification.

The response includes a status property. When status is true, the session token is valid and the external application can use the returned user information to continue the SSO process.

When status is false, the session token is not valid and the external application should not log the user in. The message property can contain information about the reason for the unsuccessful verification.

When the session is successfully verified, the user property contains the user's information. This can include details such as the username, email address, name, designation, reporting manager, thumbnail image, profile image, and other custom profile fields configured in the uKnowva HRMS instance.

Your external application can use the information returned in the user object to create or establish the user's session in the third-party application.

Step 5: Log the User into the External Application

After the external application receives a successful response from uKnowva, verify that the response indicates a valid session and that the required user information is available.

Once these checks are successful, use the returned user information according to your application's SSO logic to create the user's session and log the user into the external application.

If the session verification fails, do not create a user session in the external application. Instead, handle the unsuccessful authentication according to your application's login and error-handling flow.

Step 6: Handle Authentication and Network Errors

Your external application should also handle cases where the uKnowva session verification service cannot be reached or does not return a valid response.

If the request fails because of a network or service error, the external application should not assume that the user has been authenticated. Similarly, if the response cannot be parsed as valid JSON, the application should treat the verification as unsuccessful and handle the error appropriately.

This ensures that the external application creates a user session only after receiving a valid and successful response from uKnowva.

Example SSO Flow

The complete SSO process works as follows.

A user opens the linked external application through uKnowva HRMS. uKnowva passes the ntk session identifier to the external application as part of the request. The external application reads the ntk value and prepares a request to the uKnowva session verification service.

The external application authorizes this request using the required Bearer token and sends the ntk along with the authorized request to uKnowva. uKnowva verifies the session and returns the authentication response.

If the response confirms that the session is valid, the external application reads the user information returned by uKnowva and creates the user's session. The user can then access the external application without entering their credentials again.

If the session verification or request authorization fails, the external application must not log the user in.

Below is a simple example on how to call this web service in PHP:

$uknowva_session_token = $_GET['ntk']; //get the session token passed by uKnowva
if(!empty($uknowva_session_token)){
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://[[uknowva.instance.url]]/index.php?option=com_custom&cmd=checkSessionToken&ntk='.$uknowva_session_token);
curl_setopt($ch, CURLOPT_TIMEOUT, 1);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
$data = curl_exec($ch);
//var_dump($data);exit;
if (!curl_errno($ch)){
curl_close($ch);

$result = json_decode($data);
if(!empty($result)){

if(is_object($result))
$result = get_object_vars($result);

if($result['status']==true){
$result = $result['user'];
if(is_object($result))
$result = get_object_vars($result);
if(is_array($result)){
// YOUR LOGIC TO LOG THE USER IN, you will find all user related info in the $result array
}
}else{
//session token is not valid
}
}else{
//the json data received was not proper
}
}else{
//Some network error occurrred, the uknowva web service could not be called
}
}

Conclusion

That’s it!

You’ve now successfully configured the SSO authentication flow for an external or third-party application in uKnowva HRMS.

If you have any questions or need additional support, feel free to contact us at This email address is being protected from spambots. You need JavaScript enabled to view it..

Was this Article helpful?