This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

About

Information about the Butler Auth software, community, docs and more.

1 - Butler Auth

An introduction to Butler Auth.

The goal of the Butler Auth project is to make it easy to add strong/flexible/custom authentication strategies to Qlik Sense Enterprise on Windows (QSEoW).

QSEoW has very good, built-in access control and authorization.
In practice this means that QSEoW enforces that users only can access resources they are allowed to access.

There is however no authentication what so ever in QSEoW.
This is quite reasonable - Qlik Sense is an analytics tool and should focus on this rather than the intricancies of ensuring that users are who they claim to be. That job is better left to those specializing in that particular field.

Butler Auth is the link between QSEoW and services that specialize in authentication and security.

Technology stack

Butler Auth is written in Node.js and runs on most modern operating systems.
Some authentication providers are developed as part of the Butler Auth project, but most come from Passport.js.

You can run Butler Auth on the same server as Qlik Sense, in a Docker container on a Linux server, in Kubernetes, on Mac OS, on Raspberry Pi (not a good idea.. but possible and proven to work).

Butler Auth is a member of a group of tools collectively referred to as the “Butler family”, more info here.

This picture might be useful to understand what Butle Auth does and how it fits into the larger system map around Qlik Sense:

Butler Auth system overview

2 - The Butler family

Please meet the Butlers. They’re a nice, wild bunch!

Butler Auth is part of a group of tools that all aim to improve, simplify or extend various aspects of Qlik products.
Most tools focus on Qlik Sense Enterprise on Windows, but some have wider use within the Qlik ecosystem.

All members of the Butler family can be downloaded from Ptarmigan Labs' GitHub page.
Development of the Butler tools is sponsored by Ptarmigan Labs AB, which is an IT consultancy company in Stockholm, Sweden.

Projects with production grade release status are (as of this writing):

Butler Auth

Makes it easier to add strong/flexible/custom authentication flows to Qlik Sense Enterprise on Windows.
Out of the box Butler Auth supports Google, Microsoft, Facebook, Okta, Auth0, LDAP and a few more authentication providers.

Butler Auth is designed to be extensible. It’s therefore relatively easy to add new authentication providers.

butler-auth.ptarmiganlabs.com (This site!)

Butler

The original Butler. Offers various utilities that make it easier to develop Sense apps, as well as simplifying day 2 operations.

butler.ptarmiganlabs.com

Butler SOS

Real-time operational metrics for Qlik Sense.
It simplifies day 2 operations ([1], [2]) and is a must-have if you are responsible for a Sense environment with more than a dozen or so users.

Key features include

  • Storing operational metrics to InfluxDB, for later viewing in Grafana dashboards.
  • Extract warnings and errors from Sense. Makes it much easier to detect (and act!) on issues as they happen, rather than in retrospect much later.

butler-sos.ptarmiganlabs.com

Butler CW

Butler Cache Warmer. Cache warming is the process of proactively forcing Sense apps to be loaded into the Sense server’s memory, so they are readily available when users open them.

Once again - if your Sense environment serve more than a dozen users, you should consider a cache warming tool.

github.com/ptarmiganlabs/butler-cw

Butler App Duplicator

No matter if you are a single developer creating Sense apps, or have lots of developers doing this, having app templates is a good idea:

  • Lowered barrier of entry for new Sense developers.
  • Productivity boost when developing Sense apps.
  • Encouraging a common coding style and standard across all apps.

github.com/ptarmiganlabs/butler-app-duplicator

Butler Spyglass

This tool is mainly of interest if you have lots of QVDs and apps, but when that’s the case it’s of paramount importance to understand what apps use which QVDs. In other words what data lineage looks like.

Butler Spyglass also extracts full load scripts for all Sense apps, creating a historical record of all load scripts for all Sense apps.

github.com/ptarmiganlabs/butler-spyglass

Butler Notifier

This tool makes it easy to tap into the Qlik Sense notification API. From there you can get all kinds of notifications, including task reload failures and changes in session state (user login/logout etc).

github.com/ptarmiganlabs/butler-notifier

Butler Icon Uploader

Visual looks is important when it comes to analytics, and this holds true also for Sense apps. The Butler Icon Uploader makes it easy to upload icon libraries (for example Font Awesome) to Qlik Sense Enterprise.
With such icons available, Sense app developers can then use professional quality sheet and app icons in their Sense apps.

github.com/ptarmiganlabs/butler-icon-upload

3 - Use cases

How can Butler Auth be used?

Log into QSEoW using one of the major cloud providers' directory service

If you already use Microsoft Azure, Google, Okta or Auth0 as identify provider, you probably want to do the same also for Qlik Sense.

Log into QSEoW using LDAP for as both user and credentials

A very common setup (possibly the most common) is to use Active Directory for storing user info and credentials, and then talk to AD using the LDAP protocol.

QSEoW natively supports syncing user names from some service using LDAP, this does not include passwords though.
This is actually not authentication at all, it’s just a way to sync user names and attributes from a directory service to QSEoW, using the LDAP protocol.

LDAP can however also be used to authenticate users, and Butler Auth supports this.

One use case is thus to get both the Qlik Sense user directory info (i.e. user names and attributes) and authenticate users via LDAP.

Authenticate against Keycloak for a fully open source setup

Keycloak is a very powerful, open source identity provider.

In situations where open source solutions are preferred or mandated the combination of Keycloak and Butler Auth provides a 100% open source authentication solution for QSEoW.

Increaseed redundancy by offering sign-in via multiple channels

If you have multiple authentication solutions Butler Auth can be used to support several (or all) of them.

For example, let’s assume Okta is the primary authentication provider in your company but you also use Google’s tools (GMail, Sheets, Docs etc).

Butler Auth can then be configured for both Okta and Google authentication, with the effect that users can use either service when logging into Sense.

Use a single user account for all access to QSEoW

Sometimes you want all access to Qlik Sense to happen via a specific user account.

Admittedly, this might not be a very common scenario. But consider a trade show or other event where people should be able to test some Qlik Sense based application - ideally without having to log in at all.

You could solve this by using a Qlik Sense license that allows for anonymous users - but that’s probably overkill if the purpose is a simple demo event.

Another option is to use Butler Auth to force all access to Sense to use a single Sense account.
Given Sense’s limits on number of simultaneous sessions, only a handful (or less) people can try that Sense app at once - but it might be good enough for this specific use case.

Another use case would be to show a dashboard on a set of monitors in the office.

January 2021 note: Given how rarely people are in offices nowadays and the non-existing nature of trade shows, the use cases above might be pretty theoretical during coming months/years…

4 - Versions

Features are added, bugs are fixed. How are Butler Auth versions set?

In the spirit of not copying information to several places, the version history is kept as annotations of each release on the GitHub release page.

Version numbers include up to 3 levels, for example version 4.6.2 (which is a fictitious version):

4 is the major version. It is increased when Butler Auth has added major new features, or in other ways changed in major ways. If following this principle, breaking changes should always result in a bumped major version.

6 is the minor version. This indicates a smaller update, when one or a few minor features have been added.

2 is the patch level. When individual bugs are fixed, these are released with an increased patch level.

Note 1: Major and minor updates usually include bug fixes too.
Note 2: If a version of 5.2 is mentioned, this implicitly means 5.2.0.

5 - Contribution guidelines

How to contribute to Butler Auth.

Butler Auth is an open source project, using the MIT license.

This means that all source code, documentation etc is available as-is, at no cost.

It however also means that anyone interested can - and is encouraged to - contribute to the project!

Butler Auth is developed in Node.js, with support from various NPM modules.
Specifically, most authentication providers are implemented using Passport.js.

We use Hugo to format and generate this documentation site and the Docsy theme for styling and site structure.
Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review.
We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Discussions

We use GitHub’s discussion boards to discuss ideas, features, issues and everything else relating to Butler Auth.

Contributing to Butler Auth and this documentation site

Butler Auth itself lives in https://github.com/ptarmiganlabs/butler-auth.

The doc site lives in https://github.com/ptarmiganlabs/butler-auth-docs.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Test your changes

As obvious as it might sound: Please test your proposed changes properly before submitting pull requests.

Creating an issue

If you’ve found a problem - or have a feature suggestion - with Butler Auth or this documentation site, but you’re not sure how to fix it yourself, please create an issue in the Butler Auth or Butler Auth docs repos. You can also create an issue about a specific doc page by clicking the Create project issue button in the top right hand corner of the page.