Kyvos Web Portal Integration with Third-party Application

Applies to: Kyvos Enterprise  Kyvos Cloud (SaaS on AWS) Kyvos Azure Marketplace

Kyvos AWS Marketplace   Kyvos Single Node Installation (Kyvos SNI) Kyvos Free ( Limited offering for AWS)

Integrating Kyvos UI with third-party applications

Kyvos web application can integrate into your enterprise application for a seamless user experience.

Kyvos supports the following types of integration environments:

• Environments where the host application and Kyvos are running as separate web applications. In this case, both applications respect cross-domain requests via Cross-Origin Resource Sharing (CORS) requests.

• Environments where the Kyvos application folder is embedded/placed in the host (third-party) application folder, and both are running as a single application on a web server.

The Kyvos web portal integration with any third-party application is facilitated through HTTP calls. In an integration environment, the host application calls the Kyvos pages through an HTTP URL along with the configuration parameters. This is needed irrespective of whether the Kyvos application is physically placed under the folder structure of the host application (embedded) or Kyvos is running as a separate application.

As Kyvos UI integration is HTTP based, so the scheme in which the two web applications (host and Kyvos) are running plays an important role in integration. The following table explains the results for various combinations of HTTP protocols between Kyvos and the host application.

Browsing Kyvos use cases

The Kyvos web application introduces a URL pattern for all integration-based URL requests.

To connect/browse Kyvos functionalities (use cases), use the below URL pattern in your application:

Here, the request parameters are:

 The following figure shows Kyvos folders and workbook listing integrated with the host application.

Open

The following figure shows the Kyvos viewer integrated with the host application.

Open

The following figure shows the Add New Worksheet option in the Kyvos Visualization integrated with the host application.

User authentication mechanism

Authentication for all integrated environments depends on the type of integration, and in most cases, the Kyvos login page is not needed. Session expiry is also handled as per the authentication mechanism used in the integration.

The Kyvos pages in an integration environment, follow the authentication mechanism defined within the Kyvos application. However, if your application has already authenticated the user, then no authentication is required to open Kyvos pages.

User authentication configuration

Kyvos application needs user details for authentication and authorization to serve different requests as per the logged-in users’ roles and rights. So, the host application and Kyvos needs handshaking to transfer user details to Kyvos.

Configurations for user authentication setup in Kyvos in integration mode.

1. Set the value for the authentication provider as HOST_APP in the config.json file. Details about the integration.config.json file are mentioned below in the configuration section.

2. Provide the value for the userAuthenticationVerificationUrl property in the config.json. This property is used for passwordless SSO. See the SSO section below for details.

3. Provide value for EXT_AUTH_HEADER_ID property in the properties file. EXT_AUTH_HEADER_ID defines parameter name of request to the Kyvos page corresponding to which user token would be provided. (Details about kyvosclient.properties file is mentioned below in the configuration section).

SSO between the Host application and Kyvos application

With username and password

1. To authenticate the user and create a session, call Kyvos login REST API with username=<username> and password=<password>.
   Sample:

   http://<hostname:hostport>/kyvos/rest/login?username=<username>&password=<password>

2. If the user is successfully authenticated, this call returns a success response.
   For example, on successful authentication, REST API produces the below response.

   {      "RESPONSE":   {           "SUCCESS": "90DB354A-EE34-6827-B3E2-2BAAECE5C2E2"    } }

3. Pass the value of the SUCCESS property in the integration URL as the value of the parameter name defined by EXT_AUTH_HEADER_ID (as mentioned in the above section).

With username and token (password less authentication)

In this mode of authentication (passwordless), Kyvos relies on the host application for user authentication. Below is the flow diagram and its description:

1. The user logs into the Host web application by any authentication mechanism supported by the Host web application.

2. After the successful login of a user in the Host web application, the Host Web Application should also create a session at Kyvos to integrate Kyvos use-cases(workbook/worksheet).
   To create a session with the Kyvos application, the Host app calls a Kyvos login REST call by passing the following parameters: username, bearer token (GUID), mode=INTEGRATION, and optional custom data.
   http:<hostname>:<port>/kyvos/rest/login?username=&token=&mode=INTEGRATION&customData=

3. Now Kyvos validates parameter values received in the login REST by making the REST call to the verification endpoint with username, token, and custom data. Verification Server is provided by the Host web app and its URL is configured as userAuthenticationVerificationUrl in integration.config.json. This URL may or may not be the same as the Host web app end.

4. The verification endpoint validates the data, ensures that given parameters are valid, and returns true or false based on successful validation or failure, respectively.

5. If this verification REST call returns true as the HTTP response, then the SSO is successful, and the user session is created in Kyvos. Kyvos login REST call would return the success response for this user session. For example, on successful authentication, REST API produces the response below.

6. On Successful Validation, the Host web app embeds Kyvos use cases (workbook/worksheet) in an iframe (or new browser window) using an embed URL with sessionId as an HTTP parameter.

7. If the verification REST call returns a false response, the Kyvos login REST call will not issue any success response, and SSO will fail.

User roles and rights

The integration configurations define what options/actions are available to users. 

If any option/action is allowed in configuration, then it will be allowed to the specific user only when the user’s rights/role allows that option/action. However, if an option/action is not permitted in configuration, then that option/action will not be available to the user even if the user's role/rights suffice for that option/action.

The following figure illustrates the mechanism for actions available for users.

Configurations for Kyvos functionality

To configure Kyvos functionality in your host application, define the following configurations.

1. For X-Frame-Options: To open Kyvos pages in Iframe, set the URL of the host application in the ALLOW_FROM parameter under HTTPFilterServlet in the xml file of the Kyvos application. It is available in the <kyvos web application folder>\WEB-INF folder.

2. For user authentication handshaking: Provide values for EXT_AUTH_HEADER_ID and EXT_AUTH_PARAMETER_VALUE_TYPE properties in the properties file, as explained in the User authentication configuration section. It is available at <kyvos web application folder>\client]config folder.

3. In the properties file configure the following properties:

   1. EXT_AUTH_HOMEPAGE_URL: Provide a valid URL for the host application. Users will be redirected to this URL when the current http session in Kyvos expires.

   2. EXT_AUTH_SIGN_OUT_REDIRECT_URL: Optionally, provide this to enable logout option in Kyvos while used in Integration. In this case, users will be redirected to this URL on logout.

4. For use cases in integration mode: Kyvos provides a user-friendly configuration file where you can configure the behavior/actions/options of all the use cases when called from an integration environment.

   The configuration file integration.config.json is available at the <Kyvos web application folder>/client/config location. By default, the values for all the parameters are set to blank, which means all are enabled.

   Here’s a snippet of the integration.config.json for your reference.

5. To allow cross-site cookies, add the following line to the conf/context.xml in Kyvos web client’s Tomcat, to allow cookie handling in iFrame.
   <CookieProcessor sameSiteCookies="None" />
   Kyvos web client must be running in https (secure) mode.

6. To terminate the user session in Kyvos from integration mode, i.e., to log out from the current Kyvos session, the parent application should send the HTTP request to the following endpoint.
   http://<hostname:hostport>/<kyvosApplicationName>/kyvosIntegration.jsp?REQUEST_FOR=LOGOUT

Examples for Integrating Kyvos Use cases

Integrating workbooks into host web application

Below are some sample use cases to integrate workbooks into the host web application. 

Sample 1: Let’s assume Kyvos is running at http://<hostname:hostport>/kyvos/
This is called the BASE_URL. Kyvos worksheets or Dashboard are both referred to as worksheets in this topic.

1. Integrate a specific worksheet in the host web application.
   Let's say the user wants to integrate a worksheet named SheetDemo of IntegrationTesting
   Below are the steps to create an integration link. 

2. Login in Kyvos Application through Rest API and get auth token.

3. Create a URL like:

4. In Host Web Application set this URL in iframe source.

 Sample 2: To open a worksheet named SheetDemo of IntegrationTesting workbook in the IntegrationFolder, add the folderName in the URL.

For this, create a URL like:

Sample 3: To open a worksheet with Id Sheet1258485424224452 of Workbook with id Workbook_4545461215454, create a URL like:

 Sample 4: To open a sheet with Id Sheet1258485424224452 of Workbook with id Workbook_4545461215454 inside the folder Folder_121548454544444554,  add folderId in URL.

For this, create a URL like:

Adding worksheets in a workbook in an integrated manner from the HOST web application

Below are some sample use cases to add a worksheet in a workbook in an integrated manner from the HOST web application. 

Sample 1: To create a worksheet inside IntegrationTesting Workbook, which is present at Root. 

1. Login to Kyvos Application through Rest API and get auth token.

2. Create a URL like:

3. In Parent Application, set this URL in the iframe source.

Sample 2: To create a worksheet inside IntegrationTesting Workbook, in the IntegrationFolder, add folderName in the URL.

For this, create a URL like:

Sample 3: To create a worksheet inside Workbook with id Workbook_4545461215454 in the Root folder, create a URL like:

Sample 4: To create a worksheet inside Workbook with id Workbook_4545461215454 in folder Folder_121548454544444554, add folderId in the URL.

For this, create a URL like:

Opening a workbook from the parent application

Below are some sample use cases to open a workbook from the parent application. 

Sample 1: To open a IntegrationTesting Workbook (opening a workbook means opening the first accessible sheet).

1. Log into Kyvos Application through Rest API and get auth token. 

2. Create a URL like:

3. In Parent Application, set this URL in iframe source. 

Sample 2: To open IntegrationTesting Workbook in an IntegrationFolder, add folderName in the URL.

For this, create a URL like:

Sample 3: To open a workbook with id Workbook_4545461215454 which is available in the Root folder, create a URL like:

Sample 4: To open Workbook with id Workbook_4545461215454 in the folder Folder_121548454544444554, add the folderId in the URL. 

For this, create a URL like:

Adding a workbook from the parent application

Below are some sample use cases to add a workbook from the parent application. 

Sample 1: To create a Workbook inside the root Folder:

1. Log into the Kyvos Application through Rest API and get auth token. 

2. Create a URL like:

3. In Parent Application, set this URL in the iframe source.

Sample 2: To create a workbook inside IntegrationFolder (inside folder), add folderName in the URL.

For this, create a URL like:

Sample 3: Let’s say the user wants to create a workbook inside folder Folder_121548454544444554 , add folderId in the URL. 

For this, create a URL like:

Adding filters to worksheets from the host application

To add filters from the host application to the Kyvos dashboard/sheets, append the filter details in the GET or POST request to the Kyvos page.

For this, use any of the following methods:

1. The simplest way to send filters is by using the name-value pairs in the request.

   For example, use fieldName1 and fieldName2 parameters in the dashboard URL with fieldValue1 and fieldValue2 values, respectively. To delimit multiple name-value filter pairs, use a semicolon (;) as a delimiter. To use any other character as a delimiter, specify it in the fieldSeparator parameter.

   Sample syntax:

   This approach applies all the filters as string filters and IN LIST as the default criteria.

2. You can also provide more control over the filters, using an array of filters in JSON format as POST parameters.
   For example:

Using parameterized userAuthenticationVerificationUrl

For Kyvos embedding (integration), userAuthenticationVerificationUrl can have one or more dynamic parameters. Those parameters will be replaced with the values of top-level corresponding keys in customData JSON.
Example:
customData : {“APP_NAME”: “integration”}
 userAuthenticationVerificationUrl : “http://localhost:8081/Kyvos/<%APP_NAME%> /verifyLogin”
so the final URL for the reverse REST call will become: “http://localhost:8081/kyvos/integration/verifyLogin”
There can be multiple dynamic parameters in userAuthenticationVerificationUrl. Each parameter should have a corresponding top-level key available in customData.

Read more