Integrating your mashup or web app with Qlik Sense SaaS

There are different ways to deploy mashups and web apps depending on where they will be hosted. This topic focuses on the type of deployment where the mashup or web app leverages Qlik Sense visualizations and insights while being hosted in an external third-party domain. For information about building a mashup, see Build a simple web app.

Web apps and mashups

A mashup is a form of web app but it is important to distinguish the differences between them as they affect the way each is built. Mashups fetch JavaScript and CSS files to use the Qlik Sense capability APIs to render visualizations, create bookmarks, apply themes, and much more. Since those files are retrieved from Qlik Sense servers, you are required to use the libraries that Qlik Sense uses, for example, AngularJS and jQuery. Web apps allow you to build visualizations completely on your own, without requesting any JavaScript or CSS code from Qlik Sense servers. Web apps rely on Qlik Sense backend APIs to create the data analytics experience.

Cross-domain resource sharing

Browsers and web servers implement security policies to mitigate risks inherent with being connected to the internet. When a web server shares a resource such as an image on its own server, it is following the same-origin policy. In this case, the resource is accessed by the same protocol, domain, and port as the server. On the other hand, a secure request for a resource from a different origin (known as a cross-origin request) requires a cross-origin resource sharing (CORS) policy. CORS allows servers to specify who (the origin) can access the assets on the server. To enable cross-origin resource sharing, the site URL that is hosting the mashup or web app must be added to a whitelist on the Qlik Sense SaaSserver. This process of setting up the whitelist is known as web integration.

Qlik Sense allows you to configure CORS policies on a per web integration basis. For example, if you have two web integrations "A" and "B", and you want both to be accessible from foo.com, you need to add foo.com to the domain whitelist of both web integrations. Web integration entities are created by the tenant admin through the management console.

Authentication flow

Authentication needs to be triggered before using the Qlik Sense APIs. This is done by triggering a login process on the Qlik Sense deployment, which in turn relies on the configured IdP. If successful, an HttpOnly cookie is set and the user is redirected back to the web app or mashup solution. The HttpOnly cookie cannot be accessed through client-side scripts, which helps to mitigate cross-site scripting (XSS) attacks.

The following diagram illustrates the authentication flow for a user who is accessing a mashup or web app integrated with Qlik Sense SaaS.

Authentication flow:

1. User accesses mashup or web app site.
2. Mashup or web app redirects user to Qlik Sense SaaS backend, for example, /login?returnto=foo.com&qlik-web-integration-id=abc.
3. Qlik Sense SaaS backend redirects user to the configured IdP.
4. After the user is authenticated, the IdP redirects back to Qlik Sense SaaS backend, which sets HttpOnly cookie.
5. Qlik Sense SaaS backend redirects the user back to the original returnto URL.

Here is an example of the authentication flow. The user logs into the mysolution.com site. The user is redirected to the tenant IdP that has been set up for their Qlik Sense cloud environment, for example, https://tenant.qcs.com/login?returnto=https://mysolution.com&qlik-web-integration-id=foobar. Once the single-sign on flow is successful (including verification that https://mysolution.com was whitelisted in the entity having web integration ID 'foobar'), the user will be redirected back to their mysolution.com site where they can start using the Qlik Sense APIs. This authentication flow applies to both web apps and mashups.

Deploying web apps and mashups

Follow these steps to deploy your web app or mashup in a domain that is external to the Qlik Sense cloud environment. Differences between web apps and mashups are highlighted, where applicable, in the procedure.

1. Request the tenant admin to create a web integration entity using the Management Console. This is necessary to add the domain name of your hosting site to the whitelist. Take note of the web integration ID. Refer to Managing web integrations for details.
2. For mashups, update links in the HTML file to point to the Qlik JavaScript (.js) and Cascading Style Sheets (.css) files located in the Qlik Sense SaaS resources folder, for example: https://tenant.qcs.com/resources/autogenerated/qlik-styles.css.
3. Add the web integration ID from step 1 to the API requests.
   • For web apps, set the qlik-web-integration-id header manually for all API requests.
   • For mashups, configure the web integration ID while doing the initial configuration of the capability APIs.
   The best way to see how and where to add the web integration ID to your solution files is to consult the Web integration examples.
4. Log into the site hosting your web app or mashup to trigger the login flow. When you are authenticated, you can start using the APIs.

Examples

To get started integrating your mashups and web apps with Qlik Sense SaaS, explore the examples at Web Integration Examples.