This the multi-page printable view of this section. Click here to print.
1 - 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.
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:
2 - The Butler family
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):
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!)
The original Butler. Offers various utilities that make it easier to develop Sense apps, as well as simplifying day 2 operations.
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 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.
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.
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.
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).
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.
3 - Use cases
All your use of Qlik Sense Enterprise on Windows is subject to the licensing and other terms you have received from Qlik.
These may in theory differ between Qlik’s customers and also change over time.
You are yourself responsible for complying with terms.
If Butler Auth offers or enables features that do not align with the licesning terms you have received from Qlik, it is still your responsibility to comply with Qlik’s terms and conditions.
None of the companies and/or individuals that have at some point contributed to Butler Auth, should at any time, in any way, be held liable for how you use Butler Auth.
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
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
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!
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.
Security/DisclosureIf you discover a serious bug with Butler Auth that may pose a security problem, please disclose it confidentially to firstname.lastname@example.org first, so that it can be assessed and hopefully fixed prior to being exploited. Please do not raise GitHub issues for security-related doubts or problems.
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.
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.