Auth overview

Introduction

qlik-embed supports multiple authentication strategies:

  • Qlik Cloud
    • OAuth2 SPA: the recommended method for embedding where your embedded solution leverages the same interactive Identity Provider as your Qlik Cloud tenant.
    • OAuth2 Impersonation: the recommended method for embedding where you handle auth on your backend, or do not wish for users to be redirected.
    • API keys: a method for using per-user API keys for access. Not recommended as less secure, and doesn’t support browser websocket connections.
    • Interactive login: a method for using the current user session and a web integration to auth users. Not recommended as ineffective with browsers which block third-party cookies.
  • Qlik Sense Enterprise Client Managed
    • Interactive login: a method for using the current user session. Effective when the Qlik Sense deployment is on the same domain as the web app. Uses cookies.
  • None: a method where you must handle authenticated requests using an authorization proxy, which you must deploy as an additional component.

If you use OAuth SPA, OAuth Impersonation, or Interactive login, users accessing Qlik content via your web app will present to Qlik Sense with their own identity. This means you can use the native access controls for access to apps, as well as section access for data reduction in the app.

Add qlik-embed to your web application

Connecting to qlik-embed when you use the web components implementation requires adding a <script> element in the <head> tag. The attributes of the script element are a mix of standard and specific attributes relevant to the connection you choose.

Standard attributes, no auth

There are four attributes that must appear in <script> element for using qlik-embed web components.

  • crossorigin: tells the script element how to handle cross-origin requests. Setting the attribute to anonymous sets the script element to operate in same-origin mode.
  • type is set to application/javascript so that the web components JavaScript file is used properly by the web application.
  • src is the URI location for the qlik-embed web components library. Good practices include:
    • Using the full path to the minified source file at https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js.
    • Tagging either the major (or specific) version in the path. In the example https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js this is denoted by the @1, which will pick the latest release in major version 1 (it will match the latest in 1.x.x). You can view version information on NPM.
  • data-host is the URI hostname of the Qlik Cloud tenant, client managed server, or the authorization proxy.

This provides no auth, and looks like:

<script
  crossorigin="anonymous"
  type="application/javascript"
  src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"
  data-host="https://example.authproxy.hostname.com"
></script>

OAuth2 Single Page Application (SPA)

OAuth clients provide a way to authorize embedded content in your web application without relying on cookies.

With OAuth2 SPA, your web app and Qlik Cloud tenant should leverage the same Identity Provider for the best user experience. Users loading your web app are directed to the Identity Provider when content is requested from Qlik Cloud, and authorize the web app against the Qlik Cloud tenant hosting the Qlik Sense app.

Using an OAuth client with qlik-embed requires attributes:

  • data-client-id: OAuth client ID for the OAuth SPA client on the Qlik Cloud tenant hosting the content.
  • data-redirect-uri: the callback location in the web app after authorization.
  • data-access-token-storage: indicates to qlik-embed whether to place the token in session storage or local storage. Use session if you wish the browser to remove stored tokens at the end of the session, or local if you wish the token to persist outside of the session. session is appropriate for most use cases.

Your script should look like:

<script
  crossorigin="anonymous"
  type="application/javascript"
  src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components"
  data-host="https://tenant.region.qlikcloud.com"
  data-client-id="bee7e4b5c786af1033e6780d0bbe9727"
  data-redirect-uri="https://your-web-application.example.com/oauth-callback.html"
  data-access-token-storage="session"
></script>

Using a callback handler with data-redirect-uri

If your web app has a single page (path), then you can opt to redirect to the page containing the embedded content. This path will need to be configured in the Qlik Cloud tenant as the redirect URI, as well as placed into the script component on the embedded page.

However, most web apps have multiple paths, and in this case you should deploy a separate OAuth callback page, such as /oauth-callback.html. The purpose of this page is to act as a catch all redirect when authorization is required, simplifying whitelisting of callback URIs.

The data-redirect-uri will point back to the callback page rather than the page containing the embedded content. Qlik provides a OAuth callback handler you can use. You can create an html page and add this code, adapting the data-host attribute in this code to match that of data-host in the embedded page.

Your OAuth callback page should look like:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script
      crossorigin="anonymous"
      type="application/javascript"
      data-host="https://tenant.region.qlikcloud.com"
      src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/oauth-callback.min.js"
    ></script>
  </head>
</html>

Using API keys

Add a data-api-key attribute to the script element and set it to the API key you are using to make a connection.

Important: Do not use an API key in a production deployment because the credential appears in plain text of the web application, and it provides full access to the Qlik Cloud tenant with the permissions of the creating user.

Note: API key auth does not support websocket connections in browsers.

Your script should look like:

<script
  crossorigin="anonymous"
  type="application/javascript"
  src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"
  data-host="https://tenant.region.qlikcloud.com"
  data-api-key="<some API key value>"
></script>

Using Qlik Cloud interactive login

If your web application is not impacted by third-party cookie blocking by the browser, you can create a web integration Id in your tenant.

Use the following attributes:

  • data-web-integration set to the Id of the web integration.
  • data-cross-site-cookies set to true to instruct Qlik to allow cross-site cookie requests for embedded content, or false if your Qlik content and web app are on the same domain.

Your script should look like:

<script
  crossorigin="anonymous"
  type="application/javascript"
  src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"
  data-host="https://tenant.region.qlikcloud.com"
  data-web-integration-id="bee7e4b5c786af1033e6780d0bbe9727"
  data-cross-site-cookies="true"
></script>

Connecting to Qlik Sense Enterprise Client-managed

To connect qlik-embed to the client-managed edition of Qlik Sense Enterprise, use:

  • data-login-uri: set to http address of the Qlik Sense server including the virtual proxy path (example: https://senseserver.example.com/virtualproxypath).
  • data-cross-site-cookies set to true to instruct Qlik to allow cross-site cookie requests for embedded content, or false if your Qlik content and web app are on the same domain.

An example for connecting qlik-embed to Qlik Sense client-managed may look like this:

<script
  crossorigin="anonymous"
  type="application/javascript"
  src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"
  data-host="https://senseserver.example.com"
  data-login-uri="https://senseserver.example.com/virtualproxypath"
  data-cross-site-cookies="true"
></script>

Next steps

After you’ve configured your connection script for qlik-embed, you can begin using the component in your web application. Review the qlik-embed quick start tutorial to begin your embedded analytics journey.

ON THIS PAGE

Was this page helpful?