Package and Sign Your Connector for Distribution

🕐 6 min read

Packaging provides a convenient way to distribute your connector as a single .taco (Tableau Connector) file. Signing ensures that Tableau loads only .taco files that have been signed with a currently valid certificate, ensuring that they haven’t been tampered with. Signing is done using the Java Development Kit (JDK) and a certificate trusted by a root certificate authority (CA) that has been installed in your Java environment. When the certificate expires, Tableau rejects the .taco file unless there’s a valid timestamp.

Tableau Desktop verifies and loads signed connectors from a standard location (My Tableau Repository\Connectors) or from a user-supplied directory.

This document explains how to package and sign your connector using the TACO Toolkit command-line interface (CLI).

Before you begin
Package the connector
Sign your packaged connector with jarsigner
More information

Before you begin

Be sure you have downloaded the TACO Toolkit. For more information, see Get Started.

Package the connector

To package your connector, run this command:

taco pack

Your connector is then packaged into a single .taco file.

The taco pack command packs a taco-built project into a .taco file. This file contains your connector’s runtime artifacts generated from taco build.

The taco pack command has three stages:

prepare: This stage creates the required TACO files according to the information in the connector.json file.
validate: This stage verifies that the connector.json and required files are valid.
pack: This stage generates the .taco file for your TACO project.

After you run the taco pack command, you can test the .taco file with Tableau apps and be used for distribution.

If you have to customize any XML files for your connector, see the following note.

Note: If you have to manually customize any XML files (for example, manifest.xml), do the following: 1. Run `taco pack --prepare` to generate the XML files based on the settings on the connector.json file. 2. Modify the XML file and then run `taco pack --validate` to verify that your added content is valid. If the content is invalid, fix and validate again. 3. After the validation passes, run `taco pack --skip-prepare` to skip the initial file generation.

Sign your packaged connector with jarsigner

At this point, your connector is packaged into a single TACO file. Now you must sign the file or disable signature verification to allow it to be loaded automatically into Tableau.

Why we require connectors to be signed

Connectors are sensitive parts of the Tableau code. They handle database authentication and communicate directly with your driver. By signing the connector:

Tableau can verify the authenticity and integrity of the connector.
Customers can be confident that the plugin author is who they say they are.
Customers can know that the TACO file itself hasn’t been tampered with after it was signed.

Get your connector signed

A packaged Tableau connector (.taco) file is functionally the same as a JAR file. Tableau checks that packaged connectors are signed by a trusted certificate authority before loading them and using the default Java keystore in the JRE. Because a TACO file is fundamentally a JAR file, you can follow the Java documentation for signing JAR files.

Note: Certificates are only valid for a certain amount of time, and Tableau doesn’t load connectors with expired certificates. To mitigate this, use a timestamp as described in the following signing example. Timestamps use a timestamp authority to confirm that the certificate was valid when it was signed, even if the certificate is now expired. Also, timestamps are valid for much longer.

To sign a TACO file:

Generate a certificate signature request (CSR). You can use Java’s keytool to generate this CSR.
Send the CSR to a certificate authority that is trusted by the Java key store. Make sure that the certificate you get is a code-signing certificate.
Sign your TACO file using jarsigner.
Verify that your TACO file is signed using jarsigner as follows:
- Use the following command: jarsigner -verify path_to_taco -verbose -certs -strict If “jar verified” appears, your TACO file is ready to be used in Tableau.
- Double-check the certificate chain to make sure that the final certificate is from your certificate authority.
- Take note of when the TACO file expires. After it does, users will no longer be able to use the connector in Tableau without disabling verification and you must provide a new signed TACO file.

Signing example

Getting a certificate is a multi-step process. This example illustrates how to sign a TACO file with a basic signed certificate.

Step 1: Generate a Certificate Signing Request (CSR) file

A certificate signing request (CSR) is a request for a certificate authority (CA) to create a public certificate for your organization.

Generate a key pair using this command: keytool -genkeypair -alias your_alias -keystore your_keystore
Export the key to a certificate file: keytool -export -alias your_alias -file cert_file -keystore your_keystore
Now you can generate your certificate signing request: keytool -certreq -alias your_alias -keystore your_keystore -file certreq_file

Keep all files you’ve generated (the key pair, the keystore, and the csr) secure. You’ll need them later.

For more information about keytool arguments, see the Java Documentation about keytool on the Oracle website.

Step 2: Get the CSR signed by the certificate authority

Send the certificate signing request to the CA you want to create a certificate for you (for example, Verisign or Thawte). The CA signs the CSR file with their own signature and send that certificate back to you. You can then use this signed certificate to sign the TACO file.

After you receive/fetch the new certificate from the CA, along with any applicable “chain” or intermediate certificates, run the following command to install the new certificate and chain into the keystore: keytool -importcert cert_from_ca -keystore your_keystore

Step 3: Use jarsigner to sign the TACO file

Using the keystore you imported your signed certificate to, use jarsigner to sign your TACO file: jarsigner -keystore your_keystore path_to_taco your_alias -tsa url

The -tsa url argument is optional, but we recommend that you use it. It’s the URL to a Timestamp Authority. By adding this argument, you stamp the signed TACO file with a timestamp, extending its period of validity. While there are several free options for timestamp authority, the CA you got the certificate from will most likely have a timestamp authority you can use.

For more information about jarsigner arguments, see the Java Documentation about jarsigner.

Note: Earlier versions of the packager signed your connector using jarsigner internally. This functionality was removed in favor of the connector author calling jarsigner directly, which provides more control over how your connector is signed.

More information

For more information about web data connectors, see Connectors Built with the Web Data Connector 3.0 SDK.