Embedding Omniscope in Single-Page Applications (SPA) with Single Sign-On (SSO)

Why Embed Omniscope in Your Application?

Embedding Omniscope as part of your application can significantly enhance and augment your offering of software, apps and SaaS products, by integrating advanced data transformation, analytics, and reporting capabilities. Here are some key use cases and integration scenarios:

1. Seamless Self-Service Data-Driven Insights:

   • Deliver interactive, real-time analytics and reporting within your application without requiring external tools.
   • Empower end-users to explore their data through intuitive dashboards and custom reports.

2. Customised Branding:

   • Embed Omniscope as a fully white-labelled solution, styled to match the visual identity of your application.

3. Integration with Existing Workflows:

   • Enable users to perform advanced data processing and analysis directly within your app, integrating Omniscope’s capabilities with your existing tools and workflows.

4. Secure and Scalable Deployment:

   • Deploy Omniscope as part of your ecosystem while ensuring compliance with your authentication and data security requirements using SSO.

5. Enhanced Data Reporting for Enterprises:

   • Provide powerful reporting and visualisation features tailored for enterprise-level analytics, all within your application's environment.

Overview of Embedding Omniscope into a SPA with SSO

This document explains how to embed Omniscope within a Single-Page Application (SPA) while enabling secure user authentication via Single Sign-On (SSO) using OpenID Connect (OIDC). The example provided uses Keycloak as the Identity Provider (IdP) but can be adapted for other OIDC-compliant IdPs.

Capabilities of Embedded Omniscope in an SPA with SSO

1. Secure and Seamless Authentication:

   • Authenticate users via the SPA and propagate sessions to Omniscope using SSO.
   • Avoid additional login prompts once users are authenticated in the SPA.

2. Enhanced User Experience:

   • Omniscope reports and dashboards load within an iframe, creating a cohesive experience without switching between applications.

3. Cross-Origin Compatibility:

   • Designed for use with the same top-level domain to ensure session cookies are handled correctly.

4. Flexible Integration with Multiple Identity Providers:

   • While this document demonstrates Keycloak, the approach is adaptable for any OIDC-compliant IdP.

5. Compliance with Security Standards:

   • Adheres to Content Security Policy (CSP) directives and securely manages authentication tokens.

Step-by-Step Guide to Embedding Omniscope with Keycloak

Prerequisites

• Your SPA is hosted at http://xyz.com.
• Omniscope is hosted at http://omniscope.xyz.com.
• Keycloak is configured as the OIDC provider at http://keycloak.xyz.com.

Step 1: Domain and Network Configuration

1. Local Domain Setup (for local testing):
   • Edit your /etc/hostsfile to include the following:
     127.0.0.1 xyz.com traefik.xyz.com keycloak.xyz.com whoami.xyz.com omniscope.xyz.com

2. Production DNS:
   • Replace these local mappings with DNS records pointing to the respective services.

Step 2: Configuring Omniscope

1. Network Settings:

   • Enable external web server with the domain http://omniscope.xyz.com.

2. Security Configuration:

   • Allow rendering in iframes and configure OIDC:
     • Issuer URI: http://keycloak.xyz.com/realms/test/
     • Client ID: omniscope
     • Client Secret: (Retrieve from Keycloak).

3. Report and Folder Setup:

   • Create a project folder (e.g., spa-embed) and add reports for user access.

4. Restart Omniscope:

   • Restart after applying these changes to ensure settings are active.

Step 3: Configuring Keycloak

1. Realm and Clients:

   • Create a realm (e.g., test) and two clients (main for the SPA and omniscope for Omniscope).
   • Register callback URLs:
     • main: http://xyz.com/cb
     • omniscope: http://omniscope.xyz.com/oidc-cb

2. Test Users:

   • Add users to the realm for authentication testing.

Step 4: Supporting Services

1. Docker Compose:

   • Use a Docker configuration to launch KeyCloak and additional userful service to test the set up, like:
     • Keycloak: OIDC provider.
     • Traefik: Reverse proxy for routing.
     • Whoami: Simple test service.

2. Start Services:

   • Run the following command in the configuration directory:
     
     

     docker-compose up


Step 5: Testing the Setup

1. Access the SPA:

   • Visit http://xyz.com in an incognito session.

2. Authenticate:

   • Log in via Keycloak when prompted.

3. Verify Embedding:

   • Ensure the Omniscope iframe loads without additional authentication steps.

Key Considerations

1. HTTPS for Production:

   • Use SSL certificates for all services in production environments to ensure secure communication.

2. Cross-Site Limitations:

   • This approach requires the SPA and Omniscope to share the same top-level domain. Additional configurations are needed for cross-site setups.

3. Content Security Policies:

   • Ensure Keycloak and the SPA allow iframe embedding for token retrieval.

By embedding Omniscope in your SPA, you unlock advanced analytics and reporting capabilities directly within your application. The use of SSO ensures a seamless and secure experience for users, making it a powerful addition to your application stack.