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

Return to the regular view of this page.

Setup

Everything you wanted to know about Butler Auth configuration but never dared to ask.

1 - Which config file to use

Butler Auth can be configured using different config files. Here you learn to control which one is used.

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.)

2 - Configuration

Instructions for configuring the different parts of the Butler Auth config file.

2.1 - Logging

Logging can be done to disk and/or console, with customisable logging levels and location of log files.

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.
  ...
  ...

2.2 - Heartbeats

Heartbeats provide a way to monitor that Butler Auth is running and working as intended.
Butler can send periodic heartbeat messages to a monitoring tool, which can then alert if Butler Auth hasn’t checked in as expected.

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
  ...
  ...

2.3 - Docker healthcheck

Docker has a concept of “health checks”, which is a way for Docker containers to tell the Docker runtime engine that the container is alive and well. Butler can be configured to send such health check messages to Docker.

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)
  ...
  ...

2.4 - Uptime monitor

Butler Auth can optionally log how long it’s been running and how much memory it uses. The memory usage can also (optionally) be stored to an InfluxDB database, for later viewing/alerting in for example a Grafana dashboard.

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
  ...
  ...

2.5 - REST/web server

How to configre up the REST and web servers that Butler Auth manage.

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: 
  ...
  ...

2.6 - Auth providers

How to configure the authentication 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>
  ...
  ...

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: 
    ...
    ...