Invoking an Identity Service

The following are the methods you can use for an identity service.

• Login with provider type as Basic
• Login with provider type as OAuth/SAML
• Login with provider type as OAuth 2.0 with Deep link URL
• Login in the same browser window with provider type as OAuth 2.0
• Get Backend Token
• User Profile
• Get Provider Name
• Get Provider Type
• Use Persisted Login
• Logout
• Refresh Login

Login with provider type as Basic

// Sample code to authenticate to Quantum Fabric client			

var serviceName = "identity_service_name"; 
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var options = {};
options["userid"] = "userid";
options["password"] = "password"; // Optional values for login
options["loginOptions"]["include_profile"] = false;
options["loginOptions"]["isSSOEnabled"] = false;
options["loginOptions"]["continueOnRefreshError"] = false; //Throws error if previous IdentitySession has expired
options["loginOptions"]["persistLoginResponse"] = false;
options["loginOptions"]["isOfflineEnabled"] = false;
identitySvc.login(options, function(response) {
    kony.print("Login Success: " + JSON.stringify(response));
}, function(error) {
    kony.print("Login Failure: " + JSON.stringify(error));
});

NOTE: Please add the same identity provider name that you configured in Fabric's Identity Service tab against providerName. For example, here the identity provider name is SampleUserStore.

Additional Settings

To use the isOfflineEnabled and persistLoginResponse options in the Androd platform, you must ensure that the "Bundle Open SSL Library" option is enabled in the Quantum Visualizer Project Settings. To do this, perform the following steps.

1. On the File menu, click Settings to open the Project Settings dialog box.
2. Click the Native tab.
3. Click theAndroid sub-tab.
4. Check the option for "Bundle OpenSSL Library".

The page will look like the following example.

Login with provider type as OAuth/SAML

// Sample code to authenticate to Quantum Fabric Client
var serviceName = "identity_service_name"; 
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var options = {};
options.include_profile = true;
//browserWidget is mandatory if using the MVC Architecture
options.browserWidget = myForm.myBrowserWidget; 
var loginOptions = {};
loginOptions.isSSOEnabled = true;
loginOptions.continueOnRefreshError = false;
loginOptions.persistLoginResponse = true;

loginOptions.customQueryParamsforOAuth =

{
	"key1":"value1",
	"key2":"value2"
};
options.loginOptions = loginOptions;
identitySvc.login(options, function(response) {
    kony.print("Login success: " + JSON.stringify(response));
}, function(error) {
    kony.print("Login failure: " + JSON.stringify(error));
});

Login with provider type as OAuth 2.0 with Deep link URL

// Sample code to authenticate to Quantum Fabric Client

var serviceName = "identity_service_name"; 
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var username = "username_for_identity_service";
var password = "password_for_identity_service";
var options = {};
options["userid"] = username;
options["password"] = password;
options["UseDeviceBrowser"] = true;
options["customOAuthParams"] =
{
	"key2":"value2",
	"key3":"value3"
};
// This parameter in options will open the login url in native browser. 
// This is a deeplink url, where the control will be redirected after login.
//#ifdef android    
options.success_url = "Deep link url registered for android";
//#else    
options.success_url = "Deep link url registered for rest";
//#endif
identitySvc.login(options, function(response) {
    kony.print("Login success: " + JSON.stringify(response));
}, function(error) {
    kony.print("Login failure: " + JSON.stringify(error));
});

The sample above shows various parameters similar to the parameters of the Login with provider type as OAuth/SAML. The following two optional parameters are added further.

• UseDeviceBrowser: This parameter opens the login URL in the native internet browser of the device.
• success_url: After the log in is successful, control is redirected to the URL (deep link URL).

Deep link URL is the URL that is registered to the application. After redirection, the client calls the method handleDeeplinkCallback. (A global function)

Method signature: function handleDeeplinkCallback(query params)

// Sample code to call handleDeeplinkCallback after the deeplink redirection is done. 
// This method will be called after the deeplink redirection. 
//Need to register a call in the App services tab in App Events.
 

function appservicereq(params) {
    handleDeeplinkCallback(params); // Required validations are done and proceed with rest of login flow.                                  }

For more information on deep links, click here.

Additional Settings

From V9 ServicePack 2, Fabric supports rfc7636 for OAuth providers that use PKCE in the Authorization Code grant flow. For more information, refer to PKCE Support in Fabric.

Android

To use the PKCE feature in your Android platform, ensure that the Bundle Open SSL Library option is enabled in the Visualizer Project Settings. To enable the option, follow these steps.

1. From the left-navigation bar of Visualizer, select Project Settings.
   The Project Settings window opens.
2. From the left-panel, expand Native, and then select Android Mobile/Tablet.
3. Under Miscellaneous, select Bundle OpenSSL Library.

Responsive Web

For projects that are upgraded from earlier versions of Visualizer to V9 ServicePack 2, to use the PKCE feature for the Responsive Web platform, ensure that the JS Library Mode (Legacy) option is disabled in the Visualizer Project Settings. To disable the option, follow these steps.

1. From the left-navigation bar of Visualizer, select Project Settings.
   The Project Settings window opens.
2. From the left-panel, select Responsive Web.
3. Under General Settings, clear JS Library Mode (Legacy).

Login in the same browser window with provider type as OAuth 2.0

In the existing design of OAuth login in Quantum, the login page of an OAuth Identity provider (such as Keycloak, Google, or Okta) opens in a new window (or a new tab) on the browser. The new design implements login in the same browser window.

As the existing design does not contain any full app redirection, the SDK and Client app states do not need to be reinitialized. However, Quantum uses an SPA architecture for web apps. Therefore, in the new design, the Fabric SDK object and the client app state are reinitialized when the browser redirects to the app from the login page in the same window. To avoid losing the app state and data, make sure that you store the client app data (if any) to the local storage before invoking the Login API.

Prerequisites

• Visualizer V9 SP2 FP21, or later
• Fabric V9 SP2 FP1 HF4 (9.2.1.4), or later

NOTE: If you are using versions earlier than V9 SP2, download and install version 9.2.1.x from the Quantum Downloads page. After installing the 9.2.1.x version, install the 9.2.1.4 hotfix for the Integration Server by following the steps in the Integration Services Hotfix 9.2.1.4 release notes.

To use this feature with HTTP Integrity enabled, ensure that you are using the following software versions:

• Visualizer V9 SP3 FP31
• Fabric V9 SP3 FP1 HF16 (9.3.1.16)

Follow these steps before you consume the enhancement

1. If you are using Quantum Fabric 9.1, make sure that you upgrade to Quantum Fabric 9.2.1.4.
2. Implement the OAuth Login functionality based on the existing design, where the login page opens in a new window (new tab), and then redirects to the original window of the web app.
3. Use the existing framework APIs to store the client app data before you invoke the login API.
4. After a successful login, call the framework APIs to retrieve the client app data before proceeding with the app functionality.

Steps to implement login in the same browser window

1. Invoke the Login SDK function

   In the client code that invokes the login API, include "noPopup": true as part of the login options.

   For Example:

   var sdkObject = kony.sdk.getDefaultInstance();
   var identityServiceObject = sdkObject.getIdentityService("<providerNameOauth>");
   var options = {};
   options["loginOptions"] = {}; 
   options["loginOptions"]["noPopup"] = true; 
   options["loginOptions"]["customQueryParamsForOAuth"] = {"success_url": "<app-url>"}; /* For example -> http://example.com/apps/appName// */
   options["customOAuthParams"] =
   {
   	"key2":"value2",
   	"key3":"value3"
   };
   identityServiceObject.login(options, function (res) { 
      alert("login passed without redirection"); 
   }, function (err) { 
      alert("login failed due to" + JSON.stringify(err)); 
   });
   

   Ideally, you must save the app data or app state before calling the login API. However, if you need to save some data during the login invocation, you can add your save handle function in the options of the login API.

   For example:

   options["loginOptions"]["customDataSaveHandle"] = function(successCallback,failureCallback)
   {
   	/* Perform a task
   	successCallback(); //Call successCallback if the task is completed successfully
   	failureCallback(); //Call failureCallback  if you want to abort the login as you were not able to save custom data or state */
   }
   

    

   NOTE:
   

   • In the login options, you must pass the Success URL parameter (which is the web app URL) as part of the "customQueryParamsForOAuth" key.
   • In the Identity console, under Advanced → Redirect URL on successful authentication
     • If you have selected Allowed URL list, make sure that the specified Success URL is whitelisted.
     • If you have selected Any URL, you do not need to whitelist any URLs.

     

2. Configure an App Service event in the App Lifecycle in the Visualizer project

   In your Visualizer project, in the App Events section, select the App Service and then attach a function, for example: CustomerAppServiceFunction.

   

   Make sure that you define the specified function (CustomerAppServiceFunction) in a JS Module.

   For example:

   function customerAppServiceFunction(eventObject)
   {
   var loginResponse = eventObject.loginResponse;
   if (loginResponse)
   {
   	if (loginResponse.isError == false)
   	{
   	  //login complete, can return next form
   	  return FormAccountDetails;
   	}
   	else
   	{
   	  //login failed, can return error/retry form
   	  return FormError;
   	}
   }
   }
   

Known Issues and Limitations

• To test the OAuth login flow in same browser window, you must publish the web app to a Fabric server, and then run tests on the published web app URL.
• This feature cannot be tested on Visualizer Live Preview.
• This feature is not supported in legacy builds of the SPA and Desktop Web channels.
• Manual initialization of the SDK is not supported for this feature. Therefore, make sure that the Visualizer app is linked to the Fabric app before building or generating a live preview.
• Login must be completed after all the lifecycle events of the Visualizer app have been invoked.
• Transient login (multi-login) is not supported in this feature.

Get Backend Token

IMPORTANT: The Get Backend Token API is deprecated.

// Sample code to get backend token for provider
var serviceName = "identity_service_name";
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var options = {
    "requestParams": {
        "refresh": "true"
    }
};
var forceFromServer = false;
identitySvc.getBackendToken(forceFromServer, options, function(response) {
    kony.print("Backend token is: " + JSON.stringify(response));
}, function(error) {
    kony.print("Failed to get backend token: " + JSON.stringify(error));
});

For more information on how to configure session timeouts, refer to How to Configure App Session Settings.

getSecurityAttributes (new API)

This API can retrieve backend identity response.

/*sample snippet for invoking getSecurityAttributes API*/

var sdkObject = kony.sdk.getCurrentInstance();
var identityObject = sdkObject.getIdentityService("<<Identity-Provider-Name>>");
identityObject.getSecurityAttributes(function (response) {
   alert('Attributes - '+JSON.stringify(response));
}, function (error_response) {
   alert('failed to fetch attributes due to' + JSON.stringify(error_response));
});

User Profile

//Sample code to get user profile details
var serviceName = "identity_service_name"; 
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var forceFromServer = false;
identitySvc.getProfile(forceFromServer, function(response) {
    kony.print("User profile is: " + JSON.stringify(response));
}, function(error) {
    kony.print("Failed to fetch profile: " + JSON.stringify(error));
});

Get Provider Name

//Sample code to get provider name
var providerName = authClient.getProviderName();

NOTE: The authClient is the IdentityService object.

Get Provider Type

// Sample code to get provider name
var serviceName = "identity_service_name"; 
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var providerName = identitySvc.getProviderName();

NOTE: The authClient is the IdentityService object.

Use Persisted Login

When the login option (persistLoginResponse) is set as true, the auth response is stored in the datastore of the client device. You can invoke the usePersistedLogin API to check if the login response was stored.

If the API returns true, you can use the services authorized by that login without having to sign in again.

If the API returns false, you need to get authorized again. The persisted response is cleared only when you sign out.

Return Type: Boolean

// Sample code to retrieve the claims token from the data store.
var serviceName = "identity_service_name";
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var isLoginPersisted = identitySvc.usePersistedLogin();

Logout

// Sample code to logout from auth service
var serviceName = "identity_service_name";
// Get an instance of SDK
var client = kony.sdk.getCurrentInstance();
var identitySvc = client.getIdentityService(serviceName);
var options = {};
options["slo"] = true;
options["browserWidget"] = myForm.browserWidget;
options["logoutOptions"]["customOAuthParams"] =
{
	"key2":"value2",
	"key3":"value3"
};
identitySvc.logout(function(response) {
    kony.print("Logout success: " + JSON.stringify(response));
}, function(error) {
    kony.print("Logout failure: " + JSON.stringify(error));
}, options);

Refresh Login

Refresh login API refreshes the identity session (enabled for refresh) with backend auth server to give new internal auth tokens that are mapped with refreshed backend tokens.

Input

• successcallback : Function
• failureCallback : Function
• options: JSON

// Sample code to invoke refresh login
var sdkObject = kony.sdk.getCurrentInstance();
var identityObject = sdkObject.getIdentityService("<<Identity-Provider-Name>>");
var options = {};
options["retain_backend_refresh_token"] = true;
options["customOAuthParams"] =
{
	"key2":"value2",
	"key3":"value3"
};
identityObject.refreshLogin(function(res) {
    alert('refresh login success');
}, function(err) {
    alert('refresh login failed' + JSON.stringify(err));
}, options );

NOTE: This Refresh Login API will not work until login is done on same identity provider with refresh enabled mode.

The API is supported from App Services version 9.1.0.3 or higher.

The API is not supported from On-premies V9.1 hotfix onwards.

An error information will be shown in following cases:

• When refreshLogin is invoked without performing login with loginOptions containing the enable_refresh_login key equals to true, following error will be shown.

  /*sample code for performing login with refresh enabled options to enable working of refreshLogin API*/
  var sdkObject = kony.sdk.getCurrentInstance();
  var identityObject = sdkObject.getIdentityService("<<Identity-Provider-Name>>");
  var options = {
      "loginOptions":
          {
              "enable_refresh_login": true
          }
  };
  
  identityObject.login(options, function (response) {
      alert('login success');
  }, function (error_response) {
      alert('login failed due to' + JSON.stringify(error_response));
  });
  
  

• If Refresh login (offline_access scope) is not supported on backend identity provider, the error response contains the following key values:

  • errcode : 108

  • errmsg : "Required refresh tokens to enable refresh login are null or undefined"

• If the Enable Refresh Login check box was not set to true (not selected) in Fabric console, the error response contains the following key values:

  • errcode : 108

  • errmsg : "Required refresh tokens to enable refresh login are null or undefined"