Single Sign On (Kyvos Reporting and Your Application)

Single Sign-On (SSO) enables your users to access Kyvos Reporting reports directly from your application without signing in separately to Kyvos Reporting.

With SSO configured, users authenticate only with your application. Your application then securely exchanges authentication information with Kyvos Reporting and launches reports within your portal, providing a seamless reporting experience.

This integration is designed for embedding Kyvos Reporting functionalities like reports within your web application while maintaining centralized authentication and authorization.

Supported Scenario

This integration supports:

Web application integration
Embedded functionalities
Parameterized report execution
JWT-based authentication

How SSO Works

The following sequence describes the authentication and report-launch process:

A user signs in to your application.
The user selects any operation within your application.
Your application generates a JWT token containing Kyvos Reporting user information.
Your application sends the JWT token to Kyvos Reporting.
Kyvos Reporting validates the token and user.
Kyvos Reporting generates a session token.
Your application launches the required object like reports using the returned session token.
Report parameters are passed to Kyvos Reporting for contextual filtering.
The report is displayed within an iframe inside your application.
When the user signs out of your application, a Kyvos Reporting logout API is called to terminate the reporting session.

Prerequisites

Before implementing SSO, complete the following prerequisites.

Configure Public and Private Keys

JWT authentication uses asymmetric encryption.

Your application

Store and use the private key for signing JWT tokens.

Kyvos Reporting

Place the corresponding public key at:

<Kyvos_Reporting_Setup_Location>/Jakarta/webapps/kyvosReporting/client/config/

File name:

SSOPublic.pem

Kyvos Reporting uses this public key to verify JWT signatures.

Create the Integration User

Create a user in Kyvos Reporting under the Host Application organization type. The same user must also be present in Kyvos having access to the required semantic models and associated objects.

This user should:

Have access to all objects/reports that will be exposed through your application.
Have access to all required datasets.
Be used for all SSO requests.

Configure Cross-Site Integration Settings

Configure the required CORS, iframe, and cross-domain settings in Kyvos Reporting.

Refer to your Kyvos Reporting integration configuration documentation for details.

Security Requirements

Implement the following security requirements:

Use HTTPS for all communication between your application and Kyvos Reporting.
Use JWT tokens signed with RS256.
Protect private keys from unauthorized access.
Validate token integrity and expiration before granting access.
Ensure secure transmission of user information and business parameters.

JWT Token Structure

Your application must generate a JWT token using the RS256 algorithm.

JWT Header

{
  "alg": "RS256",
  "typ": "JWT"
}

JWT Payload Example

{
  "userId": "UserX",
  "orgID": "OrgX"
}

For integrations that use a single service account, the same userId and orgID values are sent for every request.

Authenticate with Kyvos Reporting

After generating the JWT token, call the Kyvos Reporting login endpoint.

Login URL

https://<server>:<port>/KyvosReporting/ReportController.jsp?TOKEN=<JWT_Token>&ACTION_CODE=LOGIN

What Happens

Kyvos Reporting validates:

JWT signature
Token integrity
Token expiration
User existence
User authorization

If validation succeeds, Kyvos Reporting generates and returns a Kyvos Reporting session token.

Launch Kyvos Reporting Operation

Use the returned Kyvos Reporting token to launch objects or reports.

Launch URL

https://<server>:<port>/KyvosReporting/LaunchPortal.jsp?OnAuthSuccess=<Encoded_URL_Studio_Report>&kyvosReportingToken=<Returned_Token>&<Parameter1>=<Value1>&<Parameter2>=<Value2>

For example: Studio Report URL

The encoded report URL should reference the required Studio report.

Example:

InteraController.jsp?ACTION_CODE=001&OPERATION_TYPE=VIEW&REPORT_ID=<ReportID>&REPORT_FORMAT=htm&MENU_NAME=<ReportName>&DSGN_MODE=STUDIO

Passing Report Parameters

Append report parameters to the launch URL.

Example:

https://<server>:<port>/KyvosReporting/LaunchPortal.jsp?OnAuthSuccess=<Encoded_URL_Studio_Report>&kyvosReportingToken=<Returned_Token>&Region=East&HotelID=1001

These parameters are passed directly to the report and can be used for query-level filtering.

This allows a single Kyvos Reporting user account to display different data based on the parameters supplied by your application.

Embed Reports in Your Application

After constructing the report URL, render it inside an iframe.

Example:

<iframe
    src="<Generated_Report_URL>"
    width="100%"
    height="100%">
</iframe>

Users remain within your application while viewing Kyvos Reporting objects or reports.

Logout Integration

To synchronize logout between your application and Kyvos Reporting, call the Kyvos Reporting logout endpoint when users sign out.

Logout URL

https://<server>:<port>/KyvosReporting/ReportController.jsp?ACTION_CODE=LOGOUT

This invalidates the Kyvos Reporting session and prevents further access using the existing session token.

Backward Compatibility

Kyvos Reporting maintains compatibility with existing integrations.

Existing Integrations

Existing integrations that pass the user ID directly on the ReportController URL continue to function without modification.

Performance Recommendations

To ensure optimal performance:

Use HTTPS with modern TLS versions.
Minimize report payload size.
Pass only required report parameters.
Reuse existing report definitions instead of generating reports dynamically.
Ensure network connectivity between your application and Kyvos Reporting has low latency.