Authentication with the Capability APIs

[Francis_Kabinoff]

I’ve seen a few people ask how to authenticate from an app built with the Capability APIs recently, and while there’s a lot of resources regarding authentication with Qlik Sense in general, I thought it could be helpful to some people to discuss a few details when using the Capability APIs.

Let’s clear up one thing right away. There’s no endpoint to call to pass along a username and password and authenticate users. Qlik Sense is not an identity provider. If you don’t already have an identity provider and expect Qlik Sense to handle that for you, that’s just not how it works.

There are two more things to keep in mind. Requiring authentication is going to trigger CORS, so make sure your app is whitelisted. And when you use the Capability APIs you must load some CSS files and a require.js file, but fetching those files requires that you are authenticated. If you don’t take care of authentication before trying to load those files, then loading them is going to fail.

When you configure your virtual proxy to use an authentication module the virtual proxy will redirect you to the authentication module when authentication is required. You can either use the default authentication module or build a custom authentication module.

The default authentication module uses Windows authentication (NTLM/Kerberos) and can authenticate Windows users. It’s relatively simple to configure. Just choose ticket as your authentication pattern and define either “Windows,” to show a popup, or “Form,” to be redirected to a new window with a form, in the windows authentication pattern field. The “Form” pattern will only work if your app is behind the virtual proxy.

You can also create and use a custom authentication module. To configure your virtual proxy to use a custom authentication module choose ticket as your authentication pattern and then enter the address of your custom authentication module in the authentication module redirect URI field.

Just how should you create your custom authentication module? There’s really not one answer to that question. The basic idea is that you need to get a ticket from the proxy API, and then request a resource behind the proxy with the ticket included as a query parameter. That will return a response with a set-cookie header and create a session cookie that will be used to authenticate all subsequent requests. But how you go about this really depends on your individual case. I’ll give you a couple of examples.

If your app itself is behind the virtual proxy (created in dev-hub or uploaded to extensions and served from Qlik Sense), then the best flow would probably be for your authentication module to redirect to a login form which verifies the user’s identity, gets a ticket, and redirects the user back to the app with the ticket appended as a query parameter. Since the app itself is behind the virtual proxy this will consume the ticket and create a session.

If your app is not behind the virtual proxy but already has the user information available (from a session cookie for your app, for instance) then your authentication module can request a ticket and return the targetUri (part of the response returned when a ticket is requested, generated by the initial request URI) with the ticket appended. This is exactly what the qlik-auth library for node.js does so check that out if you are interested in this pattern.

If your app is not behind the virtual proxy and does not have user information before it requests resources from behind the virtual proxy then your authentication module should redirect to a login form to verify the user’s identity, get the ticket, and then consume the ticket (you can just make a get request to the /qps/user endpoint) before redirecting the user back to where they came from.

You can also completely skip the authentication module redirect stuff and just check if the user has a session, and if not, handle it. Just remember that the resources (the CSS and require.js files) will have failed to load if you try to load them in the head of the document and you are not authenticated, so you’re going to need to make sure they load somehow. Generally, if I’m skipping out on the authentication module I’ll asynchronously load those assets once authentication is complete. You can use JWT or ticket authentication for this, but if you use ticket authentication Qlik Sense will try to use either the default authentication module or a custom authentication module depending on whether you’ve specified an authentication module redirect URI, so you may see some errors.

The idea is to just make a call to the /qps/user endpoint (prefixed with the virtual proxy you want to authenticate to of course). The response will contain a value for session, either an object with user information, or the value “inactive.” If it’s inactive, you can do something like show the user a login form which submits to an endpoint that either returns a JWT or a ticket from the QPS API, and then make a request to the /qps/user endpoint again, passing the JWT in the headers or the ticket as a url parameter, in order to receive the response with the set-cookie header which will create the session cookie. Then you can load the assets and carry on with the rest of the app.

That’s all I have for now. If you have any questions you can jump on the Qlik Branch Slack and subscribe to the authentication channel or ask me below.