Auth providers

• 1: Auth0
• 2: Facebook
• 3: Google
• 4: Keycloak
• 5: LDAP
• 6: Local file
• 7: Microsoft
• 8: Okta
• 9: Single user

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.

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.

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.

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.

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.

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

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.

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.

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.