AltTabPy is not supported by Tableau and is an independent project which (partially) implements TabPy API v1. The project itself is located on GitHub – https://github.com/innobi/AltTabPy.
In this post, I will demonstrate how to configure TabPy to require username and password, how to manage users for TabPy and how to connect from Tableau (both Desktop and Server) to TabPy with specifying credentials.
User Management for TabPy
After TabPy is installed (read Tableau Installation Instructions for how to install it) you can use tabpy-user command-line utility for adding and updating TabPy user accounts.
The utility itself supports a set of parameters such as a path to passwords file, operation, username and so on. Run tabpy-user -h to see all the parameters.
Adding a User
To add a user specify a username, a path to passwords file, password and add operation, e.g.:
c:\TabPy>tabpy-user add -u alice -f c:\TabPy\tabpypwd.txt -p P@ssw0rd
Parsing passwords file c:\TabPy\tabpypwd.txt...
Passwords file c:\TabPy\tabpypwd.txt not found
Adding username "alice"
Adding username "alice" with password "P@ssw0rd"...
Added username "alice" with password "P@ssw0rd"
In the example above the user alice with password P@ssw0rd was added to file c:\TabPy\tabpypwd.txt.
You can also let the utility generate a password for you simply skipping -p <Password> parameter:
c:\TabPy>tabpy-user add -u bob -f c:\TabPy\tabpypwd.txt
Parsing passwords file c:\TabPy\tabpypwd.txt...
Found username alice
Authentication is enabled
Generated password: ")7!f}dA_K=hrF7{x"
Adding username "bob"
Adding username "bob" with password ")7!f}dA_K=hrF7{x"...
Added username "bob" with password ")7!f}dA_K=hrF7{x"
In the example above new user bob was added to the same password file with password )7!f}dA_K=hrF7{x.
Updating User Password
It is possible to update the password for a user with update command, e.g.:
c:\TabPy>tabpy-user update -u alice -f c:\TabPy\tabpypwd.txt -p Secret_D0nt_Te11
Parsing passwords file c:\TabPy\tabpypwd.txt...
Found username alice
Found username bob
Authentication is enabled
Updating username "alice"
Updating username "alice" password to "Secret_D0nt_Te11"
In this example alice‘s password was changed to Secret_D0nt_Te11.
What’s Inside Passwords File?
The password file is just a text file with user names and hashed passwords on each line. If you open the file you will see something like this:
alice edb6473a71775f48538c1cee15dc41269302b06b79260c70ce149d1b24a4192f764570702d5449fa2712c0a99d0db9216c1a452f07a3a3b44dca1b491cd7d516
bob 7716853bdc91132fe4bef86adaac0ae6fa9cf474c5b075e89880fcd21834d2bb16266eb65d0be0a8faa2ee48342708350b95af4af3caebbb8044f59341fcfab6
Those long codes are actually the hashes for the passwords. Instead of keeping passwords in plain text or encrypted form TabPy uses hashes. What it does is makes it impossible (rather incredibly expensive) to recover passwords from those hashes. If you wonder how the passwords are hashed – at the moment TabPy uses PBKDF2 method with 10000 iterations (https://en.wikipedia.org/wiki/PBKDF2).
Deleting a User
Since the password file is just a text file you can delete a user with any text editor simply deleting the whole line with the user name in it.
Configuring TabPy with Authentication
Now when you have the passwords file you can point TabPy to it so it knows to require credentials with all the requests to serve.
NOTE: any changes for the password file do not affect any running instances of TabPy – you will need to restart TabPy for the changes to take effect.
In previous post TabPy: modifying default configuration it was shown how to changes some (or all) TabPy configuration parameters with a config file. Let’s create a config file to turn on authentication as well. I am storing the following configuration in c:\TabPy\tabpy_auth.conf:
[TabPy]
TABPY_PWD_FILE = c:\TabPy\tabpypwd.txt
As you can see the only configuration parameter I am modifying there is the password file path. In real-life scenarios, you will have logger settings, port, timeout and any other of the parameters documented at TabPy Custom Settings page.
Now let’s start TabPy with the config:
c:\TabPy>tabpy --config c:\TabPy\tabpy_auth.conf
...
DEBUG:tabpy.tabpy_server.app.app:Parameter TABPY_PWD_FILE set to "c:\TabPy\tabpypwd.txt" from config file or environment variable
INFO:tabpy.tabpy_server.app.util:Parsing passwords file c:\TabPy\tabpypwd.txt...
DEBUG:tabpy.tabpy_server.app.util:Found username alice
DEBUG:tabpy.tabpy_server.app.util:Found username bob
INFO:tabpy.tabpy_server.app.util:Authentication is enabled
...
INFO:tabpy.tabpy_server.app.app:Web service listening on port 9004
TabPy is running with authentication on!
Connecting from Tableau
For Tableau to communicate with TabPy when credentials are required you need to configure the product with username and password. As mentioned at TabPy Authentication page basic authentication is used at the moment (https://en.wikipedia.org/wiki/Basic_access_authentication) which means username (login) and password sent with each HTTP request to TabPy. This is why it is highly recommended to use a secured communication channel rather than plain text. For how to configure secure connection read Configuring HTTP vs HTTPS documentation page.
Tableau Desktop
For Tableau Desktop go to the main menu, Help, Settings and Performance, Manage External Service Connection. The screenshots below are for Tableau 2019.4.2:
Set connection type to be TabPy/External API, enter Server (host) and Port for your TabPy instance (localhost and 9004 on the screenshot below), set check mark for Sign with username and password and enter credentials for a user:
To confirm the credentials are valid click Test Connection button and popup message with confirming success (or failure details) will show:
Tableau Server
To configure Tableau Server connection to TabPy with authentication follow instructions at TSM Security page. At the moment this post is being written the latest available version of Tableau Server is 2019.4.2 and the steps will be setting up a connection and applying the changes:
It is very easy to install (with pip install tabpy command) TabPy and start (with tabpy command) TabPy instance… but what if you need to make changes is some configuration settings? You may want to use a different port because the default 9004 is in use by some other application, or you may need to run multiple TabPy instances on the same machine for some reason. Or you want to change the level of logging for it to be more/less verbose or location of the log file.
The first thing to look at is the documentation page for how to customize TabPy settings. As you can see there are some settings which names start with TABPY_ prefix – those can be overwritten with environment variables.
Modifying individual settings with environment variables
If you only need to modify one or two parameters the simplest way to do so is to set the value for the parameter by setting the environment variable with the same name. Example for Windows for how to modify default TabPy port:
(Python 3.6) C:\Users\oleks_000>set TABPY_PORT=6311
(Python 3.6) C:\Users\oleks_000>tabpy
2020-01-20,16:45:59 [DEBUG] (app.py:app:207): Parameter port set to "6311" from config file or environment variable
...
2020-01-20,16:45:59 [INFO] (app.py:app:93): Web service listening on port 6311
For macOS and Linux use export TABPY_PORT=6311 command instead of set command in the example above.
The environment variable set in the way shown above won’t keep its value between terminal sessions – as soon as the terminal is closed not just the value of the variable but the variable itself won’t exist anymore.
This is one reason to use a configuration file to preserve configuration settings. Another reason is in the file you can modify multiple settings at once and even have set of files for different configurations.
I stored the file as c:\tabpy\demo.conf and now can use it when starting TabPy with specifying custom configuration using --config command-line parameter :
(Python 3.6) C:\Users\oleks_000>tabpy --config c:\TabPy\demo.conf
2020-01-20,17:02:12 [INFO] (app.py:app:280): Loading state from state file c:\users\oleks_000\appdata\local\conda\conda\envs\python 3.6\lib\site-packages\tabpy\tabpy_server\state.ini
2020-01-20,17:02:12 [INFO] (app.py:app:311): Password file is not specified: Authentication is not enabled
2020-01-20,17:02:12 [INFO] (app.py:app:327): Call context logging is disabled
2020-01-20,17:02:12 [INFO] (app.py:app:110): Initializing TabPy...
2020-01-20,17:02:12 [INFO] (callbacks.py:callbacks:42): Initializing TabPy Server...
2020-01-20,17:02:12 [INFO] (app.py:app:113): Done initializing TabPy.
2020-01-20,17:02:12 [INFO] (app.py:app:67): Setting max request size to 262144000 bytes
2020-01-20,17:02:12 [INFO] (callbacks.py:callbacks:62): Initializing models...
2020-01-20,17:02:12 [INFO] (app.py:app:93): Web service listening on port 6311
What are those logger settings I see in the configuration file?
Short answer – those are Python logger settings documentation for which you can find at Python logger documentation page. With those setting you can control what is logged (how verbose is the logging), where the log entries are stored (console, file, etc.), in what format (what is in the logged message), how to format timestamp for a message and so on.
Before showing steps you can upgrade you TabPy to the latest pre-release version some terminology needs to be explained (all the explanations are generalized and are not exact):
TabPy release – a packaged snapshot of TabPy sources and artifacts with a tag (version) attached to it. You don’t need to use any of the releases in any way unless you are a contributor to TabPy. Releases are created when some feature, improvement or significant bug fix is added to the codebase. All releases can be seen at https://github.com/tableau/TabPy/releases.
Pre-release – specific version for which all quality confirmation hasn’t been done yet. You can see some releases are marked as Pre-release and some other as Verified.
TabPy package – TabPy release (not exactly, but very close to it) published on pypi.org. All the packages from the site can be installed on user environment with pip install <package_name> command.
TabPy pre-release packaged is published on test.pypi.org instead but is technically the same package which later when promoted to Verified release is published on pypi.org.
Why would you want or need to install or upgrade your TabPy to pre-release package? The only two reasons are:
There is a feature you need, or
There is a bug fix you need.
However, some warning has to be made:
Pre-release packages are not tested to the full and only meant to be used to unblock a scenario with a new feature or a bug fix.
Pre-release packages won’t necessarily be approved ever and can be recalled.
Pre-release packages may contain breaking and incompatible changes.
Upgrading from a pre-release package to a release may not be possible.
There may not be any bug fixes, improvement or investigations on pre-release packages.
How?
Actually installing or upgrading to a pre-release package is as simple as specifying repository with pip command parameter. For test.pypi.org the parameter is -i https://test.pypi.org/simple/. And the whole command to install the latest pre-release package is
If the pre-release version works for you – keep using it until you need to upgrade for the newer version. You can upgrade (or rather try to upgrade – see the warnings above) to a newer pre-release package as shown in the previous section. Or you can even upgrade to the newer “official” package with the regular pip install --upgrade tabpy command.
In case when the upgrade is not possible for any reason you’ll need to uninstall your current TabPy with pip uninstall tabpy command and simply install it again.
TabPy allows deploying functions that can be called from Tableau side (more technical details are at Using Deployed Functions documentation page). With that feature, you may create a repository of models (this is what I call deployed functions in this post) with many entries with time. And at some moment the question of getting the list of all available models arises.
There are at least 3 ways to find out what models are available for a specific instance of TabPy. Let’s look at them.
Option 0. Index Page (updated Feb 02, 2020)
With TabPy v0.9.0 release you can just open your TabPy instance host:port in a browser and deployed models together with some other data will be displayed on the page.
Option 1. TabPy Logs
TabPy outputs some logging data in the console and the same log entries are preserved in a log file. The lines you are looking for have “Load endpoint: ” with a model name following it (endpoint here is just another name for a deployed function). In the screenshot below you can see models PCA, Sentiment Analysis, ttest, add, and anova being loaded on TabPy startup and available for being used in Tableau calculations.
Option 2. TabPy State File
On TabPy startup, it informs in the log output about state file location (example in the screenshot below). State file is used by Tornado web-server which TabPy is built around.
The log entry shows the location for the state file. In the file itself, there is [Query Objects Service Versions] section which lists all the deployed models. As you can see the same models you can find in TabPy logs are listed in the section.
Option 3. Use the API, Luke
In the Invoking TabPy API with Postman post, I explained how to use Postman to call TabPy API. And using the API is the best way for this scenario as well – implementation may (and will) change in the future (what is logged, how and where, how functions are deployed and preserved, where the state is preserved and so on) but the API hides all those details.
As documented for /endpoints method it returns a list of all deployed models. And Postman file in TabPy repo has the method in the collection. Simply use that method (specify your TabPy address) and you’ll see something like this:
Returned JSON lists all the deployed models and their properties.
