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 toanonymous
sets the script element to operate insame-origin
mode.type
is set toapplication/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 in1.x.x
). You can view version information on NPM.
- Using the full path to the minified source file
at
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 insession
storage orlocal
storage. Usesession
if you wish the browser to remove stored tokens at the end of the session, orlocal
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 totrue
to instruct Qlik to allow cross-site cookie requests for embedded content, orfalse
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 the HTTP address of the Qlik Sense server including the virtual proxy path (example:https://senseserver.example.com/virtualproxypath
).data-cross-site-cookies
set totrue
to instruct Qlik to allow cross-site cookie requests for embedded content, orfalse
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.