Examples

• 1: Auth providers
• 1.1: Auth0
• 1.2: Facebook
• 1.3: Google
• 1.4: Keycloak
• 1.5: LDAP
• 1.6: Local file
• 1.7: Microsoft
• 1.8: Okta
• 1.9: Single user
• 2: Customizing the demo site
• 3: Butler Auth is observable

1 - Auth providers

Demo web page

Butler Auth includes a small demo web site that makes it easy to try the various authentication providers (assuming you have accounts with them, of course).

The site is just a single page with links to each authentication provider supported by Butler Auth:

Note:
The demo site has hard coded links to a specific Qlik Sense Enterprise on Windows server.
This means you can view the demo site above, but when clicking the links you won’t be able to connect to the Sense server.

Instructions for customising the demo site are available here.

1.1 - Auth0

Auth0 is an interesting authentication provider in that they offer both a user directory service, but also “passthrough authentication” to other auth providers such as Google, GitHub, Microsoft etc.

It’s thus possible to set up Butler Auth to work with Auth0, and then via Auth0 get access to their entire list of supported auth providers.

Butler Auth configuration

The settings in the config file are:

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>

Auth0 configuration

These are the general steps to set up Auth0 for use with Butler Auth.

Create application

1. Log in to your Auth0 dasboard (https://manage.auth0.com/dashboard).

2. Go to the applications section, then create a new application. You can go through the step-by-step wizard, but it’s usually easier to just fill in the needed fields on the Settings tab.

3. Fill in the specifics of your application on the Settings tab. There are lots of fields here, the important ones are

   1. Name: Application’s name. “Qlik Sense Enterprise” or “Butler Auth” could be good names, but anything goes.
   2. Description: Not mandatory, but it’s a good idea to write down a few words what the Auth0 does and its intended use cases.
   3. Application Logo: If you want your users to see a logo when authentication, this is where it’s set.
   4. Application Type: Set to “Regular Web Application”.
   5. Token Endpoint Authentication Method: Set to “Post”.
   6. Allowed Callback URLs: This one is important from a security perspective. Set to the fully qualified domain name (FQDN) of Butler Auth, for example https://qliksenseauth.ptarmiganlabs.net:8761/auth/auth0/redirect. This is a list of URLs that Auth0 is authorized to call back to once the user has been successfully authenticated.
   7. The rest of the fields on the Settings tab can be left at default values. But do review then anyway - your specific use case may require some additional settings to be set!
      
      

4. Move on to the Connections tab. If you have previously set up “connections” (which is Auth0’s word for other authentication providers), this is where you enable them.

1.2 - Facebook

Facebook offers authentication using OAuth 2.0.

Butler Auth configuration

The settings in the config file are:

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>

Facebook configuration

General steps to set up Facebook Login for use with Butler Auth.

Create application

1. Log in to Facebook’s developer site https://developers.facebook.com.

2. Go to the applications section, then create a new application:
   “Create App” > “Build Connected Experiences” > Enter app name and contact email > “Create App” > “Not a robot..”.

3. Add the Facebook Login product to the newly created app:
   Click “Set Up” on the Facebook Login product > “Other” as platform.

4. Open the basic settings:
   

   1. Set a “Display Name”.
   2. Enter a relevant “Contact Email” address.
   3. Enter a link for your “Privacy Policy URL”.
   4. Enter a link to your GDPR policy (or similar).
   5. Upload an app icon. It will be shown to users when authenticating via Facebook.
   6. Review remaining fields and fill in as needed for your specific use case.

5. Copy the App ID and App Secret from the screen above to the Butler Auth config file.

1.3 - Google

Google offers authentication using OAuth 2.0.

Butler Auth configuration

The settings in the config file are:

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>

Google configuration

General steps to set up Google for use with Butler Auth.

Create application

1. Log in to Google Cloud. The dashboard provides a good overview of your Google cloud assets.
2. Go to the “Credentials” section (https://console.developers.google.com/apis/credentials) of the API & Services page. Make sure to select the correct project in the drop-down at the top of the page.
3. Create a new client ID:
   1. “CREATE CREDENTIALS” (button at top) > “OAuth client ID” > Application typ “Web application”
   2. Enter desired name in the “Name” field.
   3. Add valid callback URIs. The one responsible for Butler Auth is https://<FQDN of Butler Auth>:<Butler Auth REST port>/oauth2callback. Note that Butler Auth’s REST API port can be changed in the main config file of Butler Auth. At least one URI is required.
      Click “Create”.
   4. Take note of the client ID and secret. Copy them to the corresponding fields in Buther Auth’s config file.
4. Set up an OAuth consent screen that will be shown to users when they authenticate to Qlik Sense using their Google credentials.

1.4 - Keycloak

Butler Auth configuration

The settings in the config file are:

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

Keycloak configuration

General steps to set up Keycloak for use with Butler Auth.

In the examples below Keycloak is available at http://qliksenseauth.ptarmiganlabs.net:8082.
This works for demonstration purposes, but in a production scenario https should be used.

1. Log in to the Keycloak admin console.

2. If you don’t already have a Keycloak realm, create one via the menu in the upper left corner.

3. Fill in the realm settings. The screen shots below only gives some guidance, you are STRONGLY encouraged to review all settings. The Frontend URL is the URL where Butler Auth will call Keycloak.

4. Open the Clients menu on the left. Add a new one.

5. Fill in the details of the new client.

   … and lower part of that page…
   The Valid Redirect URIs is a list of approved/allowed sources. Only calls originating from these URIs will be handled by this Keycloak realm/client.
   In our case, this is the callback URL of Butler Auth.

6. The Credentials tab contains the Client secret that should be copied to Butler Auth.

7. The settings on the remaining tabs of the client configuration are used to fine-tune the authentication setup. The default values should work as a starting point though.

8. If you don’t already have any users in Keycloak it’s easy to set up one for testing purposes. Open the Users menu on the left. Click the Add user button in upper right corner.

   

Keycloak Identity Brokering

Keycloak has a cool feature similar to the one offered by Auth0, where you can use another, 3rd party identity provider for the actual authentication work.

For example, you can set up Butler Auth to use Keycloak (and have all the benefits offered by Keycloak), and then have Keycloak forward the authentication requqests to IdPs such as Microsoft, Google, Facebook, LinkedIn, Twitter, GitHub and others.

1.5 - LDAP

Butler Auth configuration

The settings in the config file are:

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: 

Using Butler Auth’s built-in login page

If you want to use the built-in login page to begin with, it’s configured like this:

1. Let’s assume Butler Auth is hosted at https://butlerauth.company.com, with the http server set up to listen on port 8081.
   The demo web UI showing all the authentication providers is then available at https://butlerauth.company.com:8081/auth-providers.html.
2. In order to use the demo login page you should set the ButlerAuth.authProvider.ldap.url to https://butlerauth.company.com:8081

Here is the built-in LDAP login page:

LDAP configuration

Configuring the directory server (which Butler Auth talks to using the LDAP protocol) is beyond the scope of this site.

1.6 - Local file

Butler Auth configuration

The settings in the config file are:

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

Using Butler Auth’s built-in login page

If you want to use the built-in login page to begin with, it’s configured like this:

1. Let’s assume Butler Auth is hosted at https://butlerauth.company.com, with the http server set up to listen on port 8081.
   The demo web UI showing all the authentication providers is then available at https://butlerauth.company.com:8081/auth-providers.html.
2. In order to use the demo login page you should set the ButlerAuth.authProvider.localFile.url to https://butlerauth.company.com:8081

Here is the built-in local file login page:

Userfile format

The file containing user credentials is YAML-formatted:

users:
  - username: anna
    fullName: Anna Svenson
    password: aaa
    comment: Root admin user
  - username: joe
    fullName: Joe Jonson
    password: bbb
    comment: Regular user

1.7 - Microsoft

Butler Auth configuration

The settings in the config file are:

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>

Microsoft configuration

These are the general steps to set up Microsoft for use with Butler Auth.

1. Log in to the Miceosoft Azure portal.

2. Go to the App registrations page.

3. The screen shots below show a minimum configuration - you should review all fields to make sure the configuration is correct for your specific use case.

   On the application overview tab you find the Client ID, among other things.

   On the Branding tab you can upload an image that’s shown when users authenticate.

   On the Authentication tab you set the Redirect URIs. This is the URL where Butler Auth is running, appended with “/auth/microsoft/redirect”.

   On the Secrets tab you find the Client secret that should be copied to the Butler Auth config file.

1.8 - Okta

Butler Auth configuration

The settings in the config file are:

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: 

Okta configuration

These are the general steps to set up Okta for use with Butler Auth.
In the screen shots below Okta’s free tier is used - things might look different for you.

1. Sign into Okta. Go to the Applications tab:

2. Create a new “Web” application and give it a good name:

   Fill in Name, Base URIs (which is the Butler Auth URL) and Login redirect URIs (which is Butler Auth’s Okta callback URL). Review the other fields to make sure they match your use case. Click Done.

3. Add users as needed.

1.9 - Single user

Butler Auth configuration

The settings in the config file are:

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.

2 - Customizing the demo site

Butler Auth demo site

A single web page provides an easy way to try out the different auth providers:

The demo site - how does it work?

Each auth provider included on the demo site has a link that takes the user to Qlik Sense. For example, clicking the Google icon the user will be sent to https://senseprod.ptarmiganlabs.net/ba-google.

senseprod.ptarmiganlabs.net is a Qlik Sense Enterprise on Windows server, with a virtual proxy called ba-google (hint: ba=butlerauth).

That virtual proxy has the usual settings plus a link to a “authentication module” that should be used.

The authentication module is - surprise - part of Butler Auth. More specifically the REST API of Butler Auth has an endpoint named /auth/google.

With Butler Auth’s REST API being hosted at https://qliksenseauth.ptarmiganlabs.net:8761 (this is all set in the main config file), the full URL for the virtual proxy’s authentication module is https://qliksenseauth.ptarmiganlabs.net:8761/auth/google.

Customizing the demo site

The list below should be a good starting point if you want to customize the demo site to your own server/network/Qlik Sense environment.

Configure http server

Butler Auth’s build in web server is always enabled, but must be configured.
Given the config below the web server will be running at https://qliksenseauth.ptarmiganlabs.net:8081.

https is enabled using the specified certificate/key. In this case the certificate is not password protected (the password field is empty).

ButlerAuth:
    server:
        web:                        # The web/http server used to serve the sample login pages included in Butler Auth
            host: qliksenseauth.ptarmiganlabs.net   # Hostname of the http server. Would be container name when running under Docker. 
            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/cert/cert.cer
                key: /path/to/cert.key
                password: 

Create Qlik Sense virtual proxies

You can have many virtual proxies in Qlik Sense, even if you have just a single Sense server.
Each virtual proxy implements exactly one authentication method, or uses anonymous access to Sense.

If you want to try all the auth providers offered by Butler Auth, you need to create one virtual proxy for each provider:

An example of a virtual proxy configuration for Google authentication is found up above on this page.

Modify the demo site

The demo site is included in the GitHub repository and in the image on Docker Hub. It’s located at /src/html in the GitHub repository.

The html pages are reasonably basic, but a general understanding of html, css and Javascript is needed to understand how they work.

You must do some changes before using the demo site with your Sense server. Failing to do this will cause the authentication flows to fail, simply because the demo site won’t find your Sense server.

The needed changes are quite simple: Search for https://senseprod.ptarmiganlabs.net in all files in the demo site and replace that URL with the URL to your Sense server.

Other than that, the pages only use paths relative to the http server’s base URL, meaning that the pages should work in your Sense environment without any changes. You might want to change look-and-feel etc though - feel free to use the provided pages as inspiration!

3 - Butler Auth is observable

Heartbeats

Butler Auth has an optional heartbeat feature, which when enabled will call a specific URL with a configurable interval.

A typical scenario is to use a monitoring tool such as Healthchecks.io to ensure that the heartbeats arrive on schedule.
That tool can then alert if the heartbeats don’t arrive on time.
Healthchecks.io is available both as a Docker image for self-hosting and as a SaaS offering.

Configuration of heartbeats is described here.

Here is a self-hosted Heahlthcheck.io instance used to monitor the Butler family of tools:

Uptime monitor with metrics in InfluxDB

Another aspect of monitoring is to keep track of the internals of the service in question.

Butler Auth’s “uptime monitor” is an optional feature that can be enabled in the config file.

When enabled it will send metrics on how much memory Butler Auth uses to an InfluxDB database, as well as logging these metrics to the log files.
Logging to InfluxDB and log files can be individually enabled/disabled.
Once the metrics are in InfluxDB then can be viewed using Grafana:

Docker healthcheck

The main config file has options for enabling Docker healthchecks.
If running Butler Auth in Kubernetes this feature can useful when setting up custom avaialability logic for K8s containers.