This the multi-page printable view of this section. Click here to print.
Reference
Reference material for Butler Auth.
1 - Config file
Description of Butler Auth’s config file.
Main config file
The production_template.yaml config file looks like this:
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.
# 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
remoteURL: http://my.monitoring.server/some/path/
frequency: 60000 # Milliseconds
# 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)
# 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 instances
# Default retention policy that should be created in InfluxDB when Butler creates a new database there.
# Any data older than retention policy threshold will be purged from InfluxDB.
retentionPolicy:
name: 10d
duration: 10d
# 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:
# 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>
# 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:
Comments
-
The default location for cert/key exports is (assuming a standard install of Qlik Sense)
C:\ProgramData\Qlik\Sense\Repository\Exported Certificates\<name specified during certificate export>The files needed by Butler Auth are
client.pem,client_key.pemandroot.pem.
2 - Passport.js
Butler Auth uses Passport.js for most authentication providers.
Passport.js
Passport.js is an open source library focusing on authentication.
From their own site:
Passport is authentication middleware for Node.js. Extremely flexible and modular, Passport can be unobtrusively dropped in to any Express-based web application. A comprehensive set of strategies support authentication using a username and password, Facebook, Twitter, and more.
Butler Auth uses Passport.js for many (but not all) authentication strategies.
Given that Passport.js uses a consistent interface for all authentication strategies it’s usually quite easy to add additional authentication providers to Butler Auth.
