Silent authentication with qlik-embed and OAuth SPA

In this tutorial, you will learn how to secure qlik-embed user interfaces in your web application from end-to-end so they render without prompting for authorization, displaying unexpected pop-ups, or prompting for additional credentials.

You must have the following before you continue with the tutorial:

  • A web application connected to an OIDC-compliant identity provider, such as Auth0, which is the identity provider used in this tutorial.

  • A Qlik Cloud enterprise tenant configured with the same identity provider as your web application.

  • The clientid from a single-page application OAuth client configuration in your Qlik Cloud tenant. Configure an SPA OAuth client here and copy the clientId to your clipboard.

1.0.0 Web application

This tutorial includes a simple NodeJs application where a user must authenticate before accessing the web application. Upon authentication success, the user is redirected back to the main web page of the application where Qlik UIs are integrated using qlik-embed.

There are two ways you can setup the web application for this tutorial:

  • By cloning the repository from GitHub
  • Forking the repl on replit.com

Note: This tutorial uses the repl qlik-embed-oauth-spa. You may need to perform additional configuration to support https if you run in a local environment.

1.0.1 Clone the repository from GitHub

The repository for the web application that goes along with this tutorial is available here.

Clone the repository by issuing the git clone command in the terminal of your development environment.

git clone https://github.com/qlik-oss/qlik-embed-oauth-spa.git

OR

1.0.2 Fork the repl on replit.com

Access the qlik-embed-oauth-spa cover page and select the Fork button.

Keep the name of the repl or update with your own. Choose if you want the repl to be public or private, and then click the Fork button once more.

1.0.3 Install dependencies

From a terminal (shell) window, issue the command npm install within the directory of the cloned application.

1.0.4 Obtain the host URI for the web application

The host URI for the web application is <NAME_OF_YOUR_REPL>.<YOUR_REPL_HANDLE>.repl.co. For example, if your repl name is qlik-embed-oauth-spa and your repl handle is example then the host URI for your web application is qlik-embed-oauth-spa.example.repl.co. Identify this value and record it somewhere for later use.

1.0.5 Create and edit a dev environment file

Duplicate the example-dev.env file in the /env folder of the project. Rename the file to dev.env.

Open the file to edit it. The contents of the file will resemble:

NODE_ENV=example-dev
HOST=<HOST_APPLICATION_URI>
PORT=3000
clientId=<CLIENT_ID_FROM_IDP>
clientSecret=<CLIENT_SECRET_FROM_IDP>
idpUri=<IDP_URI>
sessionSecret=<SOME_LONG_RANDOM_TEXT_VALUE>
tenantUri=<QLIK_CLOUD_TENANT_URI>
redirectPage=oauth-callback.html

Update the following variables:

  • Change the NODE_ENV value to dev.
  • Change the HOST value to host URI you recorded in 1.0.4.
  • Update the sessionSecret value to a very long random string of characters (can include ?*!%&).
  • Modify the tenantUri value with the hostname of your Qlik Cloud tenant. An example of a tenantUri is https://example.us.qlikcloud.com.

Save the file and leave it open to continue configuration throughout the remainder of the tutorial.

2.0.0 Create and configure an application in your identity provider

The identity provider is going to handle authenticating users to the web application and to the Qlik Cloud tenant. You need the URL for the callback page in your web application for the configuration.

Note: This tutorial uses Auth0. You may choose to configure an application in a different identity provider. For more information, refer to your identity provider’s documentation.

2.0.1 Create the application

In the Auth0 administrator console, select Applications->Applications from the side menu.

Click the Create Application button.

2.0.2 Select the application type

Give your application a name and select Single Page Web Applications from the choices in the window.

2.0.3 Copy the Client ID and Client Secret

Choose the Settings tab. Copy the Domain, Client ID and Client Secret and store them for later use.

2.0.4 Add the callback URL

In the Application URIs section, add the callback URL to the web application into the Allowed Callback URLs text box. The callback URL is a formation of the host URI from 1.0.4 and the callback endpoint in the web application. The value may look like https://qlik-embed-oauth-spa.example.repl.co/callback

2.0.5 Copy the OpenID Configuration URL

Unfurl the Advanced Settings section and click the Endpoints tab. Copy the OpenID Configuration URL and store it someplace safe.

2.0.6 Save the configuration

2.0.7 Set the identity provider values in the web application env file

Go to your web application and set the following variables in the env file.

  • Change the idpUri variable value to the Domain value retrieved in 2.0.3
  • Change the clientId value to the Client ID value retrieved from the identity provider.
  • Change the clientSecret value to the Client Secret value retrieved from the identity provider.

Save the env file.

3.0.0 Configure the identity provider in Qlik Cloud

Access the management console of your Qlik Cloud tenant and click the Identity providers from the sidebar menu.

3.0.1 Create new identity provider configuration

Click Create new.

In the Type dropdown list select Interactive.

From the Provider dropdown list select Auth0.

3.0.2 Add OpenID configuration URL

Add the endpoint URL you saved in 2.0.5 to the OpenID Configuration input field.

3.0.3 Add identity provider client ID

Input the Client ID retrieved in 2.0.3 into the Client ID input field.

3.0.4 Add identity provider client secret

Input the Client Secret retrieved in 2.0.3 into the Client Secret input field.

3.0.5 Set email verified override to true

Open the Advanced options section of the configurator and turn on the email verified override option.

3.0.6 Add callback URL to the identity provider application

Switch to the application configuration within your identity provider. As with step 2.0.4, add the callback URL for your Qlik Cloud tenant to the Allowed Callback URLs input field. The callback URL for your tenant may look like https://example.us.qlikcloud.com/login/callback where example is the hostname for the tenant and us is the region.

3.0.6 Save configuration and validate the identity provider

Come back to your Qlik Cloud tenant identity provider configuration. Save the configuration and go through the validation process.

4.0.0 Configure the OAuth client

Did you set up an OAuth client? If not, do that now.

4.0.1 Add a redirect URL

Add the OAuth callback URL to the Redirect URL list. This URL points to the oauth-callback.html file supplied by the web application. The URL is a combination of this file and the host URI identified in 1.0.4. The final result may look something like https://qlik-embed-oauth-spa.example.repl.co/oauth-callback.html.

4.0.2 Add an allowed origin

Add the host URI of the web application to the Allowed origins list. The URL may look something like https://qlik-embed-oauth-spa.example.repl.co.

4.0.3 Save the OAuth configuration

Save the configuration and copy the clientId for the OAuth client to your clipboard. You are going to use this clientId value in the qlik-embed configuration.

5.0.0 Configure qlik-embed connection

Go back to the web application and open the index.html file. In the head section is a <script> element containing the properties for loading and connecting qlik-embed to your Qlik Cloud tenant.

<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_HOSTNAME>.<REGION>.qlikcloud.com"
  data-auth-type="Oauth2"
  data-client-id="<OAUTH_SPA_CLIENT_ID_FROM_TENANT>"
  data-redirect-uri="<WEB_APPLICATION_CALLBACK_PAGE>"
  data-access-token-storage="choiceOf: 'session' or 'local"
  data-auto-redirect="choiceOf: 'true' or 'false'"
  data-auth-redirect-user-confirmation="<FUNCTION_TO_REPLACE_DEFAULT_AUTHORIZE_BUTTON>"
></script>

5.0.1 Qlik Cloud tenant hostname

Modify the data-host property to point to your Qlik Cloud tenant.

  data-host="https://example.us.qlikcloud.com"

5.0.2 OAuth2 clientId

Modify the data-client-id property with the clientId provided in 4.0.3.

  data-client-id="7df548ae8b56ed81f0dad80b0f2e6e82"

5.0.3 OAuth callback page URL

Set the data-redirect-uri property to the URL for the callback page you referenced in 4.0.1.

  data-redirect-uri="https://web-application.somedomain.com/oauth-callback.html"

5.0.4 Access token storage

Set the data-access-token-storage to session.

5.0.5 Auto redirect back to the web application

Set data-auto-redirect to true.

This setting will eliminate the authorize button that appears on qlik-embed UIs before an access token is stored in the browser. What it will do is redirect to Qlik Cloud to confirm the user is authenticated and then return the access token. If the user is already authenticated, then the redirect to Qlik Cloud is silent, happening behind the scenes.

6.0.0 qlik-embed resource identifiers

When you’re embedding analytics with qlik-embed you need to tell the library which applications, charts, and UIs you want to present to users.

You can review the complete property reference for each qlik-embed ui here.

6.0.1 app-id property

You can find the app ID for an analytics app by opening the app in Qlik Cloud and observing the URL in your browser’s address bar. The guid for the app appears in the path between app and overview.

Example: https://example.region.qlikcloud.com/sense/app/a51a902d-76a9-4c53-85d2-066b44240146/overview

Populate app-id with the app guid for your app wherever you see the property in the web application index.html file.

6.0.2 object-id property

Object IDs are the unique identifiers for charts and other application objects in an analytics app. You can find the object-id of an app object a few different ways.

6.0.2.1 Developer mode in Qlik Sense

Enable the Developer menu option to app object context menus by appending /options/developer to the end of the URL of the application in your browser’s address bar.

Now you can right click a chart and select the Developer option. A window will appear with the Object ID of the visualization you can copy.

6.0.2.2 Add Sense utility

Another option is to use the Add Sense chrome extension made by former Qlikkie Erik Wetterberg. With Add Sense you can access metadata for the entire application right from the Qlik Sense application in the browser window. You can download Add Sense from the Chrome store.

6.0.3 sheet-id property

Sheet IDs are the unique identifiers for sheets in an analytics application. They are application objects and can be discovered using the Add Sense utility described in 6.0.2.2.

6.0.4 bookmark and bookmark-id property

Bookmark IDs are application objects just like charts and sheets. You can look them up the same way.

6.0.5 field-id property

The field-id property is the name of a field from the data model of an analytics application. You can find the names of fields by using the Selections tool.

7.0.0 Start the application

Once you’ve completed all the configurations, you can start the application.

7.0.1 Starting repl

If you forked the qlik-embed-oauth-spa repl on replit then press the run button at the top of the screen. Open a pop-out to a browser from the Webview tab. Authenticate and witness the qlik-embed magic.

7.0.2 Running from your local dev

If you cloned the repository from GitHub and set up the dev environment file, issue a npm run dev command from the terminal. Launch your web browser and navigate to the web application. Authenticate and witness the qlik-embed magic.

Was this page helpful?