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

Return to the regular view of this page.

Examples

Butler Auth in action!

1 - Auth providers

Examples of how the authentication providers can be configured.

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:

Demo UI for all authentication providers

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

Configuring 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>
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
issuerBaseURL The URL pointing to Auth0’s service. You get this from Auth0. For Ptarmigan Labs (who’s located in Europe/EU), the URL could be ptarmiganlabs.eu.auth0.com.
baseURL URL to Butler Auth. For Ptarmigan Labs this could be https://qliksenseauth.ptarmiganlabs.net:8761
clientId Client ID from Auth0
clientSecret Client secret from Auth0

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

  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! Auth0 create application

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

1.2 - Facebook

Using Facebook Login with Butler Auth

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>
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
clientId Client ID from Facebook
clientSecret Client secret from Facebook

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

Using Google credentials with Butler Auth.

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>
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
clientId Client ID from Google
clientSecret Client secret from Google

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

Using Keycloak with Butler Auth.

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
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
clientId Client ID from Keycloak’s *realm* > Clients > *client* > Settings page.
clientSecret Client secret from Keycloak’s *realm* > Clients > *client* > Credentials page.
host Full URL to Keycloak
realm Keycloak realm to use.
authorizationURL See below for instruction on how to get this.
tokenURL See below for instruction on how to get this.
userInfoURL See below for instruction on how to get this.

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

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

  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. Keycloak realm general

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

  5. Fill in the details of the new client. Keycloak client 1

    … 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. Keycloak client 2

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

  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 users

    Keycloak users add

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

LDAP can be used both as a source for user directory data, but also to authenticate users.

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: 
Field Description
enable Enable or disable this authentication provider. true/false.
url Tells Butler Auth where it should send the user when it’s time to enter his/her username and password. A basic web page for entering LDAP credentials is included in Butler Auth, but for production scenarios you probably want to create your own login page.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
host Host where LDAP server is running. ldap://ldap.mydomain.com is insecure/not encryptet, ldaps://ldap.mydomain.com is secure. Use ldaps if possible.
port Port to use on LDAP server. Usually 636 for ldaps, 389 for ldap.
bindUser User to log in with on LDAP server. Usually a service account of some kind.
bindPwd Password for bindUser.
searchBase The base path from which authentication attempts will be done. For an Active Directory domain called sales at company mycompany.com it could be dc=sales,dc=mycompany,dc=com'
searchFilter Filter used to determine if a user exists in the LDAP server. The example above should be a good starting point for standard-install Active Directory servers.
ca If ldaps is used and the LDAP server is configured with proper certificates that use publicly recognizable certificate authorities, this ca section is not needed. If self-signed certificates are used you need to specify the CA certificate here for ldaps to work.

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

Use a local file as your user directory.

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
Field Description
enable Enable or disable this authentication provider. true/false.
url Tells Butler Auth where it should send the user when it’s time to enter his/her username and password. A basic web page for entering local-file credentials is included in Butler Auth, but for production scenarios you probably want to create your own login page.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userFile A 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:

Local file demo 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

Using Microsoft credentials with Butler Auth.

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>
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
clientId Client ID from Microsoft
clientSecret Client secret from Microsoft

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. Microsoft application overview

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

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

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

1.8 - Okta

Using Okta with Butler Auth.

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: 
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userIdShort The provider will return the user’s email address. If userIdShort is set to true, the @ character and email domain will be stripped from the email address returned by the provider. For example, “joe@company.com” would become just “joe”. true/false.
clientId Client ID from Okta
clientSecret Client secret from Okta
oktaDomain The URL you get from Okta. Usually something like “sometext.okta.com
idp Can usually be left blank.

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: Okta applications

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

    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. Okta new web app

  3. Add users as needed. Okta users

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.
Field Description
enable Enable or disable this authentication provider. true/false.
userDirectory The Qlik Sense Enterprise user directory that will be used once the user has been authenticated by the authentication provider.
userId Qlik Sense user ID that all logins will use.

2 - Customizing the demo site

Adapt the built-in web site to work with your own Sense server.

Butler Auth demo site

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

Demo UI for all authentication 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.

Virtual proxy using Butler Auth for Google authentication

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:

Qlik Sense virtual proxies used together with Butler Auth

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

Monitoring Butler Auth, making sure it’s alive and well.

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

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:

Butler Auth memory usage visualized 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.