Getting started

• 1: Choosing an authentication solution
• 2: Installing Butler Auth
• 2.1: Choose a platform
• 2.2: Installing Butler Auth in a Docker container
• 2.3: Running Butler Auth as a native Node.js application
• 3: Setup
• 3.1: Which config file to use
• 3.2: Configuration
• 3.2.1: Logging
• 3.2.2: Heartbeats
• 3.2.3: Docker healthcheck
• 3.2.4: Uptime monitor
• 3.2.5: REST/web server
• 3.2.6: Auth providers
• 3.2.7: Qlik Sense
• 4: Day 2 operations

1 - Choosing an authentication solution

There isn’t really any right or wrong here.
What’s right for your company might be unacceptable for another company, and vice versa.

This page is intended to make you think and consider the options you have.

Commercial service or open source?

The authentication providers supported by Butler Auth generally belong to either of two categories:

• Commercial identity and authentication providers such as Okta and Auth0.
  These companies have entire teams dedicated to creating secure solutions for their customers. But the transparency is limited or non-existing. They will for sure use open standards like OAuth 2.0, OpenID etc - but you will never know exactly what their specific implementations look like.
  In other words: You will never be able to audit the code responsible for your authentication flow - you have to trust that these companies know what they are doing.

• Open source libraries provide full transparency. You can audit them if/when needed.
  The downside is that these libraries are sometimes developed by individuals or companies that no longer actively maintain them. Which in worst case could mean that new security issues are discovered in a standard authentication protocol, but the open source libraries are not quickly updated - or not updated at all.
  In this case you’d be using a library with security issues associated with it. While this is rare, it’s a real possibility.

Passport.js

Butler Auth relies heavily on the authentication strategies available via Passport.js.

This is an open source authentication library boasting 500+ various kinds of authentication strategies.

Now, there will be some duplicates (for example several different Passport.js strategies offering Google authentication) and most of those 500+ strategies will be rather obscure - with the associated risk of not being supported.
The big ones - Google, Microsoft, generic OAuth 2.0, Auth0, LDAP, OpenID etc - are generall well supported and kept up to date.
For that reason they are also used in Butler Auth.

Recommendation

So how should you reason if you have the luxury of deciding yourself what authentication solution to use?

• If low cost and ease of setup is the main focus you should go with the big, established service providers. Google, Microsoft, GitHub, Amazon etc. By using open source authentication modules you won’t have any cost for the software or service.
  These are reasonably easy to set up and get working.

• If you have high security requirements and prefer (or must use) open source, Keycloak is a good option.

  Keycloak can however be challenging to set up properly, at least if you also want to lock it down to meet specific security requirements. It’s like a Swiss army knife of authentication, with many, many tools in it…
  There is simply a risk of configuring it incorrectly and not achieve the desired security level as a result.

• If you can accept some costs associated with authentication you could use one of the commercial services. With some of them you can still use Google/Microsoft/… authentication if so desired, but you offload that integration work to the service provider.

2 - Installing Butler Auth

Getting started

Sorry - there is no installer for Butler Auth.
You will need to work a bit on the command line to set things up.

It’s not as bad as it sounds though, the instructions here should help you to get started.

Prerequisites

Either you install a few pieces of software (most notably Node.js and some node modules), or you run Butler Auth in a Docker container.

Either way you also need to edit Butler Auth’s configuration file and provide certificates exported from Qlik Sense Enterprise.

2.1 - Choose a platform

If you have access to or can set up a Docker runtime environment, this is by far the preferred way of running Butler Auth.

Installation is less error prone compared to installing Butler Auth as a Node.js app, you get all the benefits from the Docker ecosystem (monitoring of running containers etc), and upgrades to future Butler Auth ersions become trivial.

If you have access to a Kubernetes cluster, that is usually an even better option than Docker. Kubernetes can be daunting when first approached, but will give you superb reliability, failover and restarts if a server goes down or becomes unresponsive etc.

Rancher’s K3s is a great way to get started with Kubnernetes. Fully featured, well supported and a vibrant developer community.

2.2 - Installing Butler Auth in a Docker container

Prerequisites for running Butler Auth in Docker:

Installation steps

The following steps give some guidance on how to get Butler Auth running on Docker.
Here Mac OS has been used, things will look different on Linux and Windows.

➜  ~ mkdir /Users/goran/butler-auth
➜  ~ cd /Users/goran/butler-auth
➜  butler-auth mkdir -p config/certificate
➜  butler-auth mkdir sessions
➜  butler-auth mkdir log
➜  butler-auth wget https://raw.githubusercontent.com/ptarmiganlabs/butler-auth/main/src/docker-compose.yaml
--2021-01-20 13:58:54--  https://raw.githubusercontent.com/ptarmiganlabs/butler-auth/main/src/docker-compose.yaml
Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 151.101.128.133, 151.101.64.133, 151.101.192.133, ...
Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|151.101.128.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 754 [text/plain]
Saving to: ‘docker-compose.yaml’

docker-compose.yaml                                                   100%[========================================================================================================================================================================>]     754  --.-KB/s    in 0s

2021-01-20 13:58:54 (37.8 MB/s) - ‘docker-compose.yaml’ saved [754/754]

➜  butler-auth
➜  butler-auth cat docker-compose.yaml
# docker-compose.yml
version: '3.3'
services:
  butler-auth:
    image: ptarmiganlabs/butler-auth:1.0.0
    container_name: butler-auth
    restart: always
    ports:
      - "8081:8081"       # http/web server used to serve sample login forms included in Butler Auth
      - "8761:8761"       # REST API called by Qlik Sense Enterprise when users should be authenticated
    volumes:
      # Make config file and logs accessible outside of container
      - "./config:/nodeapp/config"
      - "./log:/nodeapp/log"
      - "./sessions:/nodeapp/sessions"
      - "/path/to/tls/cert:/nodeapp/config/tls"
    environment:
      - "NODE_ENV=production"
    logging:
      driver: json-file
      options:
        max-file: "5"
        max-size: "5m"
➜  butler-auth

At this point you should

1. Export certificates from the Qlik Sense QMC. Export a full set of certificates in PEM format, with or without passwords on the certificates. If a password is used it must also be specified in Butler Auth’s config file.
2. Copy the certificates to the ./config/certificate directory.
3. Copy the template config file from the GitHub repository to the ./config directory, modify it as needed based on your system(s) and which Butler Auth features you want enabled.
   Rename it to for example production.yaml.
   You can actually name the config file anything, but its name has to match the NODE_ENV environment variable, as set it the docker-compose.yaml file.
4. If using the local-file auth provider, you also need a corresponding YAML file where user info is stored. There is a template file in the GitHub repository.
5. If using TLS to secure Butler Auth (you should!), the volumes entry /path/to/tls/cert:/nodeapp/config/tls in docker-compose.yaml must point to your TLS certificates.

When done, you should see something like this:

➜  butler-auth tree
.
├── config
│   ├── certificate
│   │   ├── client.pem
│   │   ├── client_key.pem
│   │   └── root.pem
│   ├── production.yaml
│   └── users.yaml
├── docker-compose.yaml
├── log
└── sessions

4 directories, 6 files
➜  butler-auth

At this point everything is ready and you can start the Butler Auth container using docker-compose (IP addresses and URLs have been slightly scrambled below):

➜  butler-auth docker-compose up
Creating network "butler-auth_default" with the default driver
Pulling butler-auth (ptarmiganlabs/butler-auth:1.0.0)...
1.0.0: Pulling from ptarmiganlabs/butler-auth
22f9b9782fc3: Already exists
072739d44e4f: Already exists
5111f27e9600: Already exists
dc22afea6082: Already exists
0ad0b403cda0: Already exists
bca65cadbc25: Already exists
c1e57ccc1a03: Already exists
2571476d0e73: Already exists
e3719000bb2c: Already exists
d09cb7e3b7d4: Pull complete
76d111860f8b: Pull complete
c30b9b6a8b26: Pull complete
e75f642798c7: Pull complete
5b06a9fb8f94: Pull complete
Digest: sha256:545e81b4a638cb2f50b7718723cd60528e91a237349429279a90928c95fa420f
Status: Downloaded newer image for ptarmiganlabs/butler-auth:1.0.0
Creating butler-auth ... done
Attaching to butler-auth
butler-auth    | 2021-01-19T06:22:18.070Z info: CONFIG: Influxdb enabled: true
butler-auth    | 2021-01-19T06:22:18.075Z info: CONFIG: Influxdb host IP: 1.2.3.4
butler-auth    | 2021-01-19T06:22:18.075Z info: CONFIG: Influxdb host port: 8086
butler-auth    | 2021-01-19T06:22:18.076Z info: CONFIG: Influxdb db name: butlerauth
butler-auth    | 2021-01-19T06:22:18.413Z info: AUTH-LOCALFILE: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.415Z info: AUTH-LOCALFILE: Loading user list.
butler-auth    | 2021-01-19T06:22:18.419Z info: AUTH-LOCALFILE: Successfully loaded users from file.
butler-auth    | 2021-01-19T06:22:18.420Z debug: AUTH-LOCALFILE: Users loaded from file: [
butler-auth    |   {
butler-auth    |     "username": "anna",
butler-auth    |     "fullName": "Anna Svenson",
butler-auth    |     "password": "aaa",
butler-auth    |     "comment": "Root admin user"
butler-auth    |   },
butler-auth    |   {
butler-auth    |     "username": "joe",
butler-auth    |     "fullName": "Joe Jonson",
butler-auth    |     "password": "bbb",
butler-auth    |     "comment": "Regular user"
butler-auth    |   }
butler-auth    | ]
butler-auth    | 2021-01-19T06:22:18.421Z info: AUTH-LDAP: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.421Z info: AUTH-GOOGLEOAUTH: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.422Z info: AUTH-FACEBOOK: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.423Z info: AUTH-MICROSOFT: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.424Z info: AUTH-OKTA: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.425Z info: AUTH-KEYCLOAK: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.425Z info: AUTH-AUTH0: Setting up endpoints.
butler-auth    | 2021-01-19T06:22:18.426Z debug: HEARTBEAT: Setting up heartbeat to remote: http://healthcheck.mycompany.com/ping/12345678-1234-1234-1234-b10b81583522
butler-auth    | 2021-01-19T06:22:18.428Z info: --------------------------------------
butler-auth    | 2021-01-19T06:22:18.428Z info: Starting Butler authenticator
butler-auth    | 2021-01-19T06:22:18.428Z info: Log level: debug
butler-auth    | 2021-01-19T06:22:18.428Z info: App version: 1.0.0
butler-auth    | 2021-01-19T06:22:18.428Z info: --------------------------------------
butler-auth    | 2021-01-19T06:22:18.458Z info: MAIN: REST server now listening on butler-auth:8761
butler-auth    | 2021-01-19T06:22:18.459Z info: MAIN: Web server now listening on butler-auth:8081
butler-auth    | 2021-01-19T06:22:18.478Z info: CONFIG: Found InfluxDB database: butlerauth
butler-auth    | 2021-01-19T06:22:18.597Z debug: HEARTBEAT: Sent heartbeat to http://healthcheck.mycompany.com/ping/12345678-1234-1234-1234-b10b81583522

What you see on your screen will depend on which Butler Auth version you are using and what features are enabled.

2.3 - Running Butler Auth as a native Node.js application

While Qlik Sense Enterprise is a Windows only system, Butler Auth runs on any OS where Node.js is available.
Butler Auth has been succesfully used using standard Node.js - during development and production - on Windows, Linux (Debian and Ubuntu tested) and Mac OS.

Running as Node.js app

Prerequisites:

Installation steps

• Install node.js
  Butler Auth was developed and tested using the 64 bit version of Node.js. The most recent LTS (Long Term Support) version of Node.js is a good choice for running Butler. At time of this writing, Node.js 14.5 is used.

• Decide where to install Butler Auth
  It is usually a good starting point to run Butler Auth on a Sense server.

  On the other hand, you might want to keep the Sense servers as clean as possible (with respect to software running on them). If that is a priority you should install Butler Auth on some other server. A small “utility” or “misc” server can often be useful for running various add-on services to Qlik Sense.

  The bottom line is that Butler Auth can run on any server, as long as Node.js is available and there is network connectivity to the actual Qlik Sense server(s).

• Download Butler Auth
  Download the repository zip from the releases page file or clone the Butler Auth repository using your git tool of choice. Both options achieve the same thing, i.e. a directory such as d:\node\butler-auth, which is then Butler Auth’s root directory.

• Install node dependencies
  From a Windows command prompt (assuming the Butler ZIP file/repository was extracted to d:\node\butler-auth):

  d:
  cd \node\butler-auth\src
  npm install
  

  This will download and install the Node.js modules used by Butler Auth.

• Configuration
  Configuration of Butler Auth is done more or less the same way as configuring for Docker, i.e. get certificates from Qlik Sense Enterprise on Windows > store them in suitable location > refer to those cert files from production.yaml file etc.
  More details are then available in the on the Configuration pages.

3 - Setup

3.1 - Which config file to use

A description of the config file format is available here.

Select which config file to use

Butler Auth uses configuration files in YAML format. The config files are stored in the src/config folder.

Trying to run Butler Auth with the default config file (the one included in the files download from GitHub) will not work - you need to adapt it to your server environment.

The name of the config file matters. Butler Auth looks for an environment variable called “NODE_ENV” and then tries to load a config file named with the value found in NODE_ENV.

For example:

• NODE_ENV=production

• Butler will look for a config file config/production.yaml.

Setting environment variables

The method for setting environment variables varies between different operating systems:

On Windows:

set NODE_ENV=production

Mac OS or Linux

export NODE_ENV=production

If using Docker, the NODE_ENV environment varible is set in the docker-compose.yml file (as already done in the sample docker-compose file.)

3.2 - Configuration

3.2.1 - Logging

What’s this?

Logging tells you what Butler Auth has done in the past.
Who logged in when, if you like.

Temporarily increasing logging verbosity can also be very useful when setting up new authentication providers.
Don’t forget to dial back the logging level once everthing works though!

Settings in config file

---
ButlerAuth:
  ...
  ...
  # Logging configuration
  logLevel: info      # Log level. Possible log levels are silly, debug, verbose, info, warn, error
  fileLogging: false  # true/false to enable/disable logging to disk file
  logDirectory: log   # Subdirectory where log files are stored. Absolute or relative path accepted.
  ...
  ...

3.2.2 - Heartbeats

What’s this?

A tool like Butler Auth should be viewed as mission critical, at least if the Qlik Sense environment as such is considered mission critical.

But how can you know whether Butler Auth itself is working?
Somehow Butler Auth itself should be monitored.

Butler Auth (and most other tools in the Butler family) has a heartbeat feature.
It sends periodic messages to a monitoring tool, which can then alert if Butler hasn’t checked in as expected.

Healthchecks.io is an example of such as tool. It’s open source but also has a SaaS option if so preferred. Highly recommended!

More info on using Healthchecks.io with the Butler family can be found in this blog post.

Settings in main config file

---
Butler:
  ...
  ...
  # Heartbeats can be used to send "I'm alive" messages to any other tool, e.g. a infrastructure monitoring tool
  # The concept is simple: The remoteURL will be called at the specified frequency. The receiving tool will then know 
  # that Butler Auth is alive.
  heartbeat:
    enable: false                     # Enable/disable healthcheck pings
    remoteURL: http://my.monitoring.server/some/path/
    frequency: frequency: 60000       # Milliseconds
  ...
  ...

3.2.3 - Docker healthcheck

Note: Sending health check messages is only meaningful when running Butler Auth as a Docker container.

Settings in main config file

---
Butler:
  ...
  ...
  # Docker health checks are used when running Butler Auth as a Docker container. 
  # The Docker engine will call the container's health check REST endpoint with a set interval to determine
  # whether the container is alive/well or not.
  # If you are not running Butler Auth in Docker you can safely disable this feature. 
  dockerHealthCheck:
    enable: false    # Control whether a REST endpoint will be set up to serve Docker health check messages
    port: 12398      # Port the Docker health check service runs on (if enabled)
  ...
  ...

3.2.4 - Uptime monitor

What’s this?

In some cases - especially when investigating issues or bugs - it can be useful to get log messages telling how long Butler Auth has been running and how much memory it uses.

This feature is called “uptime monitoring” and can be enabled in the main config file.

The logging interval is configurable, as is the log level required for uptime messages to be shown.

The memory usage data can optionally be written to InfluxDB, from where it can later be viewed in Grafana.
If the specified InfluxDB database does not exist it will be created. The same is true for the retenion policy.

Select a reasonable retention policy and logging frequency!
You will rarely if ever need to know how much memory Butler Auth used a month ago… A retention policy of 1-2 weeks is usually a good start, with logging every few minutes.

Settings in main config file

---
Butler:
  ...
  ...
  # Uptime monitor
  uptimeMonitor:
    enable: false                    # Should uptime messages be written to the console and log files?
    frequency: 300000                # Milliseconds
    logLevel: info                   # Starting at what log level should uptime messages be shown?
    storeInInfluxdb: 
      enable: false
      hostIP: <IP or host name>
      hostPort: 8086
      auth:
        enable: false
        username: user_joe
        password: joesecret
      dbName: butlerauth
      instanceTag: DEV              # Tag that can be used to differentiate data from multiple Butler Auth instances
      # Default retention policy that should be created in InfluxDB when Butler Auth creates a new database there. 
      # Any data older than retention policy threshold will be purged from InfluxDB.
      retentionPolicy:
        name: 10d
        duration: 10d
  ...
  ...

3.2.5 - REST/web server

What’s this?

Butler Auth exposes a REST server which Qlik Sense will call when a user connects to a Qlik Sense virtual proxy.
There are then different REST API endpoints for different authentication providers. The REST server is also responding to the callbacks that happen as part of for example an OAuth 2.0 authentication flow. When the authentication provider has given green light, that provider’s callback endpoint on the REST server is called.

Secondly, a http server is used to serve a sample web based login interface.
This web site is for inspiration only. It has hard coded URLs that need to be changed before it is useful in your own environment. Still, it can serve as a basis for your own, custom/branded login page for Qlik Sense.
Each authentication provider that rely on some kind of web interface for entering user name and password has a url property the main YAML config file (for example ButlerAuth.authProvider.ldap.url). Those property can be used to direct authentication requests to your own, custom login user interfaces.

The settings below control the behvaiour of those two servers.

Settings in main config file

---
ButlerAuth:
  ...
  ...
  # Server and https settings
  server:
    rest:                   # The REST server is the authentication server called by Qlik Sense.
      host: <FQDN>          # Hostname of the REST server. Would be container name when running under Docker, otherwise something like qliksenseauth.mydomain.com.
      port: 8761            # Port where the REST server will listen
      rateLimit:            # Used to limit number of authentication requests during a given time window. Used to prevent brute forcing attacks.
        enable: false       # Enable/disable rate limiting for this REST API. true/false.
        windowSize: 60000   # How long (milliseconds) is the time window we're capping # of logins for? Default 5 min if not specified.
        maxCalls: 100       # Max # of logins from Qlik Sense during time window above. Default 100 if not specified.
      tls:                  # Many 3rd party auth providers require the OAuth 2 server to use https. 
        enable: true        # Enable/disable https. While always recommended, https is strictly not needed for local file authentication, for example.
        cert: /path/to/certfile.cer    # TLS certificate file 
        key: /path/to/certfile.key     # TLS key file
        password:           # Passphrase for TLS key file, if used
    web:                    # The web/http server used to serve the sample login pages included in Butler Auth
      host: <FQDN>          # FQDN of the http server 
      port: 8081            # Port where the http server will listen
      tls:                  # Used to secure the http server with TLS. I.e. https.
        enable: true
        cert: /path/to/certfile.cer
        key: /path/to/certfile.key
        password: 
  ...
  ...

3.2.6 - Auth providers

What’s this?

A core concept of Butler Auth is that of authentication providers, or just providers.

A provider’s purpose is to offer a way to authenticate users.
Once users are authenticated they are forwarded to Qlik Sense.

Providers can be individually enabled and disabled, i.e. there are no dependencies between providers.
Likewise, there are no limitations on how many or which providers can be enabled at the same time.

Each provider has it’s own settings in the config file.
If new providers are added to Butler Auth they will need to be configured in the config file.

Settings in main config file

---
ButlerAuth:
  ...
  ...
  # Auth providers are responsible for authenticating users before they are forwarded to Qlik Sense Enterprise.
  authProvider:       
    localFile:                          # "Local file" provider reads user data from a file on disk
      enable: false                    
      url: https://<FQDN>:8081          # URL where login UI for this provider is available
      userDirectory: lab                # Qlik Sense user directory that will be used for the authenticated user
      userFile: ./config/users.yaml     # YAML file containing usernames and passwords

    ldap:                               # "LDAP" provider
      enable: false
      url: https://<FQDN>:8081          # URL where login UI for this provider is available
      userDirectory: lab                # Qlik Sense user directory that will be used for the authenticated user
      ldapServer:                       # Information about the LDAP server to authenticate against
        host: <ldap(s)://ldap.mydomain.com>    # Both normal (ldap://) and secure (ldaps://) LDAP is supported
        port: 636                       # Usually 389 for LDAP and 636 for LDAPS
        bindUser: '<domain\username>'   # Service account used to log into the LDAP server
        bindPwd: <password>             # Password of service account
        searchBase: '<dc=...,dc=...,dc=...>'    # Base path from which authentication attempts will start
        searchFilter: '(&(objectcategory=person)(objectclass=user)(|(samaccountname={{username}})(mail={{username}})))' # Filter used to get info about users in LDAP server
        tls: 
          # Settings here will override default TLS behaviour. 
          # Useful for example if your cert is for another domain wrt the host name of the LDAP server.
          # If a setting is empty it will simply be ignored by Butler Auth.
          # Necessary if the LDAP server isusing a self-signed certificate
          # Should point to a PEM coded CA certificate file.
          ca: 

    singleUser:                       # "Single user" provider
      enable: false
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userId: goran                   # A user that already exists in QLik Sense. All access to Sense will be done using this user.

    google:                           # "Google" OAuth2 provider
      enable: false
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      clientId: <Client ID>
      clientSecret: <Client secret>

    facebook:                         # "Facebook" OAuth2 provider
      enable: false
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      clientId: <Client ID>
      clientSecret: <Client secret>

    microsoft:                        # "Microsoft" OAuth2 provider
      enable: false
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      clientId: <client ID>
      clientSecret: <Client>

    okta:                             # "Okta" provider
      enable: false
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      clientId: <Client ID>
      clientSecret: <Client secret>
      oktaDomain: <Okta domain from Google admin console>  # E.q. https://myid-123456.okta.com'
      idp: 

    keycloak:                         # "Keycloak" provider
      enable: true
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      clientId: <Client ID>
      clientSecret: <Client secret>
      host: <FQDN of Keycloak server> # E.g. https://keycloak.mydomain.com
      realm:                          # E.g. ptarmiganlabs
      authorizationURL: <URL>         # E.g. https://keycloak.mydomain.com/auth/realms/<myrealm>/protocol/openid-connect/auth
      tokenURL: <URL>                 # E.g. https://keycloak.mydomain.com/auth/realms/<myrealm>/protocol/openid-connect/token
      userInfoURL: <URL>              # E.g. https://keycloak.mydomain.com/auth/realms/<myrealm>/protocol/openid-connect/userinfo

    auth0:                            # "Auth0" provider
      enable: true
      userDirectory: lab              # Qlik Sense user directory that will be used for the authenticated user
      userIdShort: true               # If true, the email domain will be removed. I.e. "joe.smith@domain.com" will be changed to "joe.smith".
      issuerBaseURL: <FQDN>           # E.g. mycompany.eu.auth0.com
      baseURL: <URL>                  # FQDN of Butler Auth, e.g. https://qliksenseauth.mycompany.com:8761'
      clientId: <Client ID>
      clientSecret: <Client secret>
  ...
  ...

3.2.7 - Qlik Sense

What’s this?

These settings tell Butler Auth where to find the certificates it needs to communicate with Qlik Sense Enterprise.

Settings in main config file

---
ButlerAuth:
  ...
  ...
  # Settings relating to Qlik Sense
  qlikSense:
    # Certificates to use when calling Sense APIs. Get these from the Certificate Export in QMC.
    certFile:
      # If running under Docker, use these paths:
      # clientCert: /nodeapp/config/certificate/client.pem
      # clientCertKey: /nodeapp/config/certificate/client_key.pem
      # clientCertCA: /nodeapp/config/certificate/root.pem
      # If running as a native Node.js app, point to where the cert files are stored:
      clientCert: /path/to/client.pem
      clientCertKey: /path/to/client_key.pem
      clientCertCA: /path/to/root.pem
      clientCertPassphrase: 
    ...
    ...

4 - Day 2 operations

Running Butler Auth

How to start and keep Butler Auth running varies depending on whether you are using Docker or a native Node.js approach.

Running as a Docker container

Starting Butler Auth is easy.
First configure the docker-compose.yml file as needed, then start the Docker container in interactive mode (with output sent to the screen). This is useful to ensure everything works as intended when first setting up Butler Auth.

docker-compose up

Once everything works as intended, hit ctrl-c to stop the service.
Then start it again in deameon (background) mode:

docker-compose up -d

From here on the Docker enviromment will make sure Butler is always running, including restarting it if it for some reason stops.

Running as native Node.js app

Starting Butler Auth as a Node.js task is easy too:

d:
cd \node\butler-auth\src
node index.js

It is of course also possible to put those commands in a command file (.bat on Windows, .sh etc on other platforms) file and execute that file instead.

Windows services & process monitors

As Butler Auth is the kind of service that (probably) should always be running on a server, it makes sense using a Node.js process monitor to keep it alive (if running as a Docker container you get this for free).

On Windows you can use the excellent Nssm tool to make Butler Auth run as a Windows Service, with all the benefits that follow (can be monitored using operations tools, automatic restarts etc).

If running Butler Auth as a Node.js app on Linux, PM2 and Forever are two good process monitors.

Monitoring Butler Auth

Once Butler Auth is running it’s a good idea to also monitor it. Otherwise you stand the risk of not getting notified if it for some reason misbehaves.

Butler Auth will log data on its memory usage to InfluxDB if

1. The config file’s ButlerAuth.uptimeMonitor.enable and ButlerAuth.uptimeMonitor.storeInInfluxdb.enable properties are both set to true.
2. The remaining InfluxDB properties of the config file are correctly configured.

Assuming everything is correctly set up, you can then create a Grafana dashboard showing Butler Auth’s memory use over time.
You can also set up alerts in Grafana if so desired, with notifications going to most IM tools and email.

The following metrics are logged to InfluxDB, in a measurement called butlerauth_memory_usage:

• heap_used
• heap_total
• external
• process_memory

Each measurement is also tagged with a tag called butlerauth_instance. This tag is set in the main config file and is used in complex environments to separate between different Butler Auth instances.

A Grafana dashboard can look like this. Note that one of the available metrics (external) is not used in this particular dashboard. It’s still logged to InfluxDB though.

There is a sample Grafana dashboard in Butler’s GitHub repo.