Page tree
Skip to end of metadata
Go to start of metadata

0 - Before you begin


If you are using a Windows machine you can skip most of these steps by using our quick installer. The quick installer sets up Write-Back for you in a simplified way, for instance it installs a PostgreSQL database and a self-signed certificate so you don't have to worry about it. Anyway all the functionality is there and you can always revert to the specific sections of this manual and enhance the deployment done by the quick installer according to your needs or even make it production ready. Hence this is the preferred approach for Windows deployments. 


The extension is required to run on a separate server and thus Tomcat needs to be installed. 

  • The domain name (URL) for the extension is required to be able to call the extension based on the name instead of IP, this name will be shown to the Desktop inside the .trex file. → We will use the server name
  • SSL Certificate, to be able to run the extension over HTTPS. Similar to Tableau Server and depends on the previous pre-requisite as the certificate mentions URL. 

Start trying right away by downloading the latest version.

0.1 - Pre-requisites

Hardware

The extension corresponds to a Web application running on Tomcat that acts as a broker for manual inputs, hence the necessary hardware requirements depend on the number of inputs placed by users concurrently. The following minimum hardware requirements and recommendations apply to all computers running the Write-Back extension including physical hardware and virtual machines (VMs):

  • RAM: 8G
  • Disk: 30GB
  • Architecture: 64bits
  • Internet connection


We heavily recommend to differentiate the machines where you run your database instance and the machine where the extension (server) will be.


Software

  • Operative System:
    • Windows:
      • Windows 10, Windows Server 2016
    • Linux
      • RHEL-like distributions: Red Hat Enterprise Linux,  CentOS
      • Ubuntu
      • Debian 
  • At least Java 8 installed
  • One of the supported SQL database instances

0.2 - Authentication

The extension allows multiple ways of doing user authentication. The methods that require integration with third-party systems are listed below with specific instructions on what you need to do before beginning the installation. 

Kerberos and Active Directory

Kerberos authentication is optional. If Kerberos is already being used (with Tableau Server for instance), the extension supports this type of authentication, the configuration just needs to point to the Active Directory server and some other parameters described below (Install Extension).

Here we provide a quick and simple way to start the set up with Kerberos.

If you are setting up Active Directory for the first time, follow these steps. If not, follow just from point 3 and forward to create the user for Kerberos.


  • Setup a technical user for the extension to enable Kerberos authentication can be the same as on Tableau Server. It will be used in chapter Configure Active Directory and Kerberos below. 
    • Set user as an SPN (service principal name)
    • Create a keytab for the user (Kerberos)


  1. Setup Active Directory
    1. Add the Active Directory Role; This is taken from this guide: (here)
      1. We skipped step one, where the DNS is changed;
      2. On step 13) We choose the root domain name as mycompany.com; check if the NetBIOS domain name is MYCOMPANY;
  2. Add a new user for the client on AD;
    1. On Server Manager click on Tools and select Active Directory Administrative Center;
    2. On the left side choose mycompany (local) and then Users;
    3. On the right select New → User;
    4. Configure a user with at least the following information (example):
      1. First Name: jon
      2. User UPN login: jon
      3. sAMAccountName: NetBIOS domain Name \ jon
      4. Setup a password
      5. On the right in Password Options choose: other password options and leave it there.
      6. In the MemberOf section make sure to add the user to the Domain User group.
  3. Setup a technical user for the extension to enable Kerberos authentication; (reference here, C.2)
    1. Create a New user like in step 2
    2. Configure a user with the following information (Example: root domain name → mycompany.com : NetBIOS → mycompany)
      1. First Name: tableauextension (These names are just as an example)
      2. sAMAccountName: tableauextension
      3. Setup a password
      4. On the right in Password Options choose: other password options and then password never expires.
    3. Head to the terminal to set this user as an SPN (Service Principal Name): (Format is: setspn -A [principal] [sAMAccountName])

      setspn -A HTTP/tableauextension.mycompany.com tableauextension
    4. Create a keytab for the user, make sure you then copy it to a place where you have access to. Use the following command:

      1. In /mapuser you should specify the Active Directory user.
      2. In /princ you should write the SPN you chose in c.
      3. Int /pass is the password defined in the AD for the user.
      ktpass /out C:\extension.keytab /princ HTTP/tableauextension.mycompany.com@MYCOMPANY.COM /mapuser tableauextension@MYCOMPANY.COM /pass * /ptype KRB5_NT_PRINCIPAL /crypto RC4-HMAC-NT
  4. Make sure to have java jdk installed, and to ease the process have it added to environment variables.


Kerberos notes

The expected output of setspn:

C:\Users\mycompany> setspn -A HTTP/tableauextension.mycompany.com tableauextension
Checking domain DC=mycompany,DC=com

Registering ServicePrincipalNames for CN=tableauextension.mycompany.com,CN=Users,DC=mycompany,DC=com
        HTTP/tableauextension.mycompany.com
Updated object

The expected output of ktpass:

C:\Users\mycompany> ktpass /out C:\extension.keytab /princ HTTP/tableauextension.mycompany.com@MYCOMPANY.COM /mapuser tableauextension@MYCOMPANY.COM /pass * /ptype KRB5_NT_PRINCIPAL /crypto RC4-HMAC-NT
Targeting domain controller: kerberos-server.mycompany.com
Successfully mapped HTTP/tableauextension.mycompany.com to tableauextension.
Type the password for HTTP/tableauextension.mycompany.com:
Type the password again to confirm:
Password successfully set!
Key created.
Output keytab to C:\extension.keytab:
Keytab version: 0x502
keysize 80 HTTP/tableauextension.mycompany.com@MYCOMPANY.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 4 etype 0x17 (RC4-HMAC) keyleng
th 16 (0xf73dfeb2619a8bd9ec299ee67dc2402f)


The expected output of kini, after the setup is complete:

C:\> kinit -k -t .\extension.keytab HTTP/tableauextension.mycompany.com
New ticket is stored in cache file C:\Users\mycompany\krb5cc_mycompany



1 - Install the Tomcat Server

Tomcat is an open-source java application server provided by Apache, it is the most popular application server for java environment.

Tomcat doesn’t work without java, so before installing tomcat on the machine, you should install a compatible java runtime version and setup JAVA_HOME environment variable. Both java and tomcat versions should be compatible(Java 8 with tomcat 8 e.g.)

  • Open Apache Tomcat home page at http://tomcat.apache.org/index.html.
  • In the left-hand Download menu, click the latest available Tomcat version.
  • Locate the Binary Distributions area and in the Core list click on the ZIP file corresponding to the required Windows version.

  • Save the ZIP file in a temporary directory.

  • Unpack the downloaded ZIP file into the target folder on the computer
  • Configure JVM options for Tomcat web server as follows:
    • For Windows, create TOMCAT_HOME/bin/setenv.bat file and write: set JAVA_OPTS=%JAVA_OPTS% -Xms256m -Xmx1024m -XX:+UseParallelOldGC -XX:PermSize=128m -XX:MaxPermSize=384m
    • Open the TOMCAT_HOME/conf/server.xml file and add the URIEncoding="UTF-8" attribute for all <Connector> elements. <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8143" URIEncoding="UTF-8"/>



1.1 - Allowing HTTPS connections on Tomcat

(required for all tableau extensions)

To run extensions on Tableau Environments (Server and Desktop) source code needs to be stored behind an HTTPS connection. Since we are running the backend on a tomcat server, we need to establish the connection through SSL (https).

To achieve it we need a keystore for tomcat and to edit the server configuration on tomcat.


Tableau Extension over SSL

The extension requires using HTTPS so it is mandatory to have a valid root certificate on the machine running tableau Desktop or Tableau Server.

If you are configuring in a test environment controlled by you, you could simply get a self-signed certificate as this will be enough for that purpose.


We provide a couple of ways of generating a certificate to use on the server the extension is running. A self-signed certificate is a simple way of creating a certificate that will work on an intranet. Certificate Authority (CA) Certificate is the proper way to set up a certificate for more broad use, with external access, for example.

When using a CA (internal, i.e., your company certificate generator tool or trusted CA, i.e., Let's Encrypt, IdenTrust, DigitCert, etc.) we recommend requesting a PKCS12 certificate as this is the simplest way to use with tomcat. Below you can see that all that is necessary is to place the certificate somewhere tomcat can access and use the connector provided.


Using a PKCS12 certificate with private key (recommended method/option #1)

This creates a certificate bundled with a private key, that can be used directly in the tomcat server.xml.

This connector replaces the one that is there already (usually commented).

Usual location is under this comment:

<!-- Define a SSL/TLS HTTP/1.1 Connector on port 8143
         This connector uses the NIO implementation. The default
         SSLImplementation will depend on the presence of the APR/native
         library and the useOpenSSL attribute of the
         AprLifecycleListener.
         Either JSSE or OpenSSL style configuration may be used regardless of
         the SSLImplementation selected. JSSE style configuration is used below.
    -->
<!--    
    <Connector port="8143" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true" >
        <SSLHostConfig>
            <Certificate certificateKeystoreFile="somefile" type="RSA" />
        </SSLHostConfig>
    </Connector>
-->

Simply add the following connector and make sure the other one is commented, like above, or simply remove it.

server.xml ssl connector
<Connector protocol="HTTP/1.1" URIEncoding="UTF-8" port="8143" maxThreads="200"
	scheme="https" secure="true" SSLEnabled="true"
  	keystoreFile="path/to/certificate.pfx" keystorePass="passwordUsedInCertificate" keystoreType="PKCS12"
	sslProtocol="TLS" clientAuth="false" />

Examples to create a PKCS12 certificate:


Certificate Authority Certificate (optional)

(https://www.digicert.com/csr-ssl-installation/apache-openssl.htm)
When it's possible to have an external valid domain that can be validated by an external authority

  1. Create a  certificate signing request (CSR)
    1. Using OpenSSL
      1. openssl req –new –newkey rsa:2048 –nodes –keyout server.key –out server.csr
         
      2. Generate Files

        1. You've now started the process for generating the following two files:

          • Private-Key File: Used to generate the CSR and later to secure and verify connections using the certificate.
          • Certificate Signing Request (CSR) file: Used to order your SSL certificate and later to encrypt messages that only its corresponding private key can decrypt.
        2. When prompted for the Common Name (domain name), type the fully qualified domain (FQDN) for the site that you are going to secure.

          Note: If you're generating an Apache CSR for a Wildcard certificate, make sure your common name starts with an asterisk (e.g., *.example.com).

        3. When prompted, type your organizational information, beginning with your geographic information.

          Note: You may have already set up default information.

        4. Now, your OpenSSL .csr file is created.

      3. Order Your SSL/TLS Certificate

        1. Open the .csr file you created with a text editor.

        2. Copy the text, including the -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- tags, and paste it into the DigiCert order form.

      4. Save Private Key

        Save (back up) the generated .key file. You need it later to install your SSL certificate.

      5. Install Certificate

        After you've received your SSL certificate from DigiCert, you can install it on your server.

Creating a keystore (with self-signed certificate) for tomcat using javatool (option #2)

https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html#Installing_a_Certificate_from_a_Certificate_Authority

Navigate to the java bin folder and the following command:

keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -validity 365 -keystore /somepath/keystore.jks

    • The -keystore is used to define the location where the keystore is going to be created. In the example the keystore is called keystore.jks and will be stored under somepath.
    • Fill the information it asks (first and last name is related to the FQDN)
      • The Fully Qualified Domain Name (FQDN) is the name of the computer in your network, usually. Example: Server name is writeback and the FQDN could be writeback.xpand-it.com
      • If the server does not have a name, simply use its IP.
    • Be sure to remember the chosen password

Self Signed Certificate

(https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/)
When it's not possible to have an external valid domain that can be validated by an external authority a self-signed certificate might be an option. Please bear in mind that the certificate will have to be installed on every machine that tries to use the extension.

  1.   Get and open the root Certificate 
  2.   Once you have the install certificate button available, select “Install Certificate”.
  3.  This will launch the Certificate Import Wizard. Make sure to choose the option “Place all certificates in the following store” and select browse.
  4.  Select Trusted Root Certification Authorities and click Ok.
  5. Click Finish on Completing the Certificate Import Wizard
  6. Reboot Tableau Desktop or Server

Edit server configuration in Tomcat

Now we need to define the connector for the HTTPS connection.

    • Navigate to the Tomcat installation folder
    • Open the config folder and then the server.xml file
    • Search for the following commented part:

      <!-- Define a SSL/TLS HTTP/1.1 Connector on port 8143
               This connector uses the NIO implementation. The default
               SSLImplementation will depend on the presence of the APR/native
               library and the useOpenSSL attribute of the
               AprLifecycleListener.
               Either JSSE or OpenSSL style configuration may be used regardless of
               the SSLImplementation selected. JSSE style configuration is used below.
          -->
      <!--    
          <Connector port="8143" protocol="org.apache.coyote.http11.Http11NioProtocol"
                     maxThreads="150" SSLEnabled="true" >
              <SSLHostConfig>
                  <Certificate certificateKeystoreFile="somefile" type="RSA" />
              </SSLHostConfig>
          </Connector>
      -->


      And changed it with the keystore you just created like so:

      <!-- Define a SSL/TLS HTTP/1.1 Connector on port 8143
               This connector uses the NIO implementation. The default
               SSLImplementation will depend on the presence of the APR/native
               library and the useOpenSSL attribute of the
               AprLifecycleListener.
               Either JSSE or OpenSSL style configuration may be used regardless of
               the SSLImplementation selected. JSSE style configuration is used below.
          -->
      
          <Connector port="8143" protocol="org.apache.coyote.http11.Http11NioProtocol"
                     maxThreads="150" SSLEnabled="true" >
              <SSLHostConfig>
                  <Certificate certificateKeystoreFile="somepath/keystore" certificateKeystorePassword="yourPassword"
                               type="RSA" />
              </SSLHostConfig>
          </Connector>
    • Then restart the server and you have your web apps running over HTTPS on port 8143.

1.2 - Setting up Tomcat as a service

Windows

As an option, you can install Tomcat as a Windows Service allowing you to start/stop the service in the background without having to go to the command line to start Tomcat.

To do so:

  1. With the command line, go to the apache-tomcat bin folder, in there there is a .bat file called service.bat
  2. Run the file like so:
    1. service.bat install TableauWritebackServer
      1. TableauWritebackServer is the name that will be used for the service, you can change this if you wish to
  3. Verify that a Windows Service now exists with that name. This service can now be used to start and stop the extension server.
  4. Additionally, depending on how your server is set up, you might want to change the owner of the service to the local machine, to do so:
    1. sc config TableauWritebackServer obj= ".\LocalSystem"

More info: http://tomcat.apache.org/tomcat-8.5-doc/windows-service-howto.html#Installing_services

2 - Install the Extension

To install Write-Back on an environment, follow the steps below:

2.1 - Download the extension

  1. Go to Support & Resources and download the latest version of the extension
  2. Change the name of the war to be just twbe.war
  3. Place the .war file in the apache-tomcat/webapps folder
  4. Re-Start the tomcat server. You will notice that after a few seconds a folder named twbe will appear in the webapps folder. From now on, all the setup that is mentioned here will be done with the files inside that folder.

2.2 - Configure Different Sites

Write-Back supports sites enabling to segregate users. Using different sites means you can write data to different DBMS and also using different authentication methods for each, guaranteeing that a user can only access the site is was configured to. To use different sites with the same extension, you need to create a new .yml file inside the sites folder under your WEB-INF\classes.

We ALWAYS need to have the default site defined. Having only a default site is equivalent to not using this feature.


This files contains two blocks, the Persistence and AuthenticationOptions block. To configure a Persistence block go ahead and visite section 2.3. The AuthenticationOptions is the block where the varying parts of each authentication method are declared, visit the authentication section and check the site specific options.

To use sites you will need to have .trex file for each site you intend to use. This means that to have a site called departmentB you will need to:

  1. create a departmentB.yml file in the sites folder
  2. create a .trex file with the URL as https://app.domain/twbe/site/departmentB

It is mandatory that both the file name and the site name are the same. 

2.3 - Configure Persistence Connections

IF you are planning to use hyper as the persistence type you willl need the following pre-requisites as well:

  • You still need a SQL database where the configuration tables with metadata will be stored.
  • You will also need to attend to the requirements to run the hyper API that can be found here.


  1. Add the necessary dependencies (e.g. SAP Hana JDBC jar) into the unpacked war folder under WEB-INF\lib;

    1. If you intend to use Hyper Persistence then you need to download the necessary files and unpack them in the mentioned folder. These files were taken directly from the Tableau Hyper API page, but we stored them here for easier access. If you want to download them directly from the Tableau page, you can find them here but make sure to download the Java ones. If you choose to download them from the Tableau site be wary that when replacing them in the web app folder it might warn you for duplicated jars.

      1. Windows: hyper.zip.
      2. Linux: hyper.zip.
      3. Mac: hyper.zip.
  2. Change configurations in your site file, located in WEB-INF/classes/sites. To configure the Persistence, we need to change different properties. 

    Property SectionProperty Section DescriptionProperty namePossible valuesDescription
    typeThis is the type of persistence that we intend to create our datasets.typeJDCB or HYPERUse JDBC when you intend to use a SQL database with a driver.

    Use HYPER when you want to use a Hyper File to store the data.

    database





    This property section is used together with the "jdbc" option in the type property.

    driver

    Example: com.mysql.jdbc.Driver

    Specify to the DriverManager which JDBC drivers to try to make Connections with.
    url
    Example: jdbc:mysql://localhost:3306/test
    JDBC URL parameter, indicating host, port and database.
    username


    The user to connect as.
    password

    password

    or

    encrypted>password

    The password to use when connecting.  This password can be written here as plain text or ciphered with our writeback-encrypt util. Be sure that the tag "encrypted>" is presented. For more details check Ciphering Database Passwords.
    auditDatabaseThis property section is used (also only needed) together with the "hyper" persistence type. It contains the same properties as the database property section. The availability of having different databases for configuration tables and your datasets is only available for hyper, for now.


    hyperThis property section is used together with the "hyper" option in the type property.directory
    The full path for the hyper file to be created to store data.


Connection Examples


JDBC Persistence type
persistence:
  type: jdbc
  database:
    driver: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/test
    username: root
    password:

The example showed above is related to MySQL. You can find more examples here.

Hyper Persistence type
persistence:
  type: hyper
  auditDatabase:
    driver: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/test
    username: root
    password:
  hyper:
    directory: /pathToHyperFile/test.hyper


Driver Strings and Url Examples for Database Properties


DatabaseDriverURL
MySQL

com.mysql.jdbc.Driver

jdbc:mysql://[HOST:PORT]/SCHEMA

PostgreSQL

org.postgresql.Driver

jdbc:postgresql://[HOST:PORT]/DATABASE?currentSchema=SCHEMA

SQL Server

com.microsoft.sqlserver.jdbc.SQLServerDriver

jdbc:sqlserver://[HOST:PORT];databaseName=DATABASE

Oracle

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@[HOST:PORT]:orcl

Snowflakecom.snowflake.cliente.jdbc.SnowflakeDriverjdbc:snowflake://[HOST:PORT]/?database=DATABASE&schema=SCHEMA
Redshiftcom.amazon.redshift.jdbc41.Driverjdbc:redshift://[HOST:PORT]/DATABASE
Sap Hanacom.sap.db.jdbc.Driverjdbc:sap://[HOST:PORT]/?currentschema=SCHEMA

For drivers compiled with a specific java version, like SQL Server and Oracle, please download the driver for your installed java version. 


Database user tips


Database user tip

It is highly recommended to create a specific database user for the extension to use. It should only have access to the extension schema where the datasets will be created as well as the configuration tables.


In the case of SQL Server, this user must be created with a default schema, as SQL Server has the requirement to always specify a schema. To add a default schema to a user, here is an example: ALTER USER XPWBTABEXT WITH default_schema = dbo; Replacing the highlighted words with the proper ones for your scenario.


In the case of Amazon Redshift, depending on the security settings, you most likely will need to add the IP of the tomcat server to be able to access the database. In the EC2 Console, there should be an option to manage Security Groups were the IP should be added to the inbound rules. This guide might help: https://docs.aws.amazon.com/redshift/latest/gsg/rs-gsg-authorize-cluster-access.html


SQL Server with encryption

It is possible to enable encryption with the SQL Server connection simply by adding a few parameters to the connection string. Example:

SQL Server encryption
persistence:
  type: JDBC
  database:
    driver: com.microsoft.sqlserver.jdbc.SQLServerDriver
    url: jdbc:sqlserver://your.sql.sever:1433;databaseName=writeback;encrypt=true;trustServerCertificate=false;hostNameInCertificate=your.sql.server
    username: username
    password: password
    schema: dbo

Tip: The password can also be encrypted: Ciphering Database Passwords.

hostNameInCertificate also accepts wildcards if you need that: hostNameInCertificate=*.database.windows.net


If a certificate is needed to connect to the SQL Server we need to add it to the trust store. Tomcat might already have a specified one, you can check that by taking a look in server.xml. Example:

 

Then it is necessary to specify the full path to the keystore as well as its password in the connection string:

SQL Server encryption
persistence:
  type: JDBC
  database:
    driver: com.microsoft.sqlserver.jdbc.SQLServerDriver
    url: jdbc:sqlserver://your.sql.sever:1433;databaseName=writeback;encrypt=true;trustServerCertificate=false;trustStore=C:\path\to\keysotre.jks;trustStorePassword=storePassword
    username: username
    password: password
    schema: dbo

To add a certificate to a keystore:

keytool -import -v -trustcacerts -alias tomcat -file yourSQLServerCertificate.cer -keystore keysotre.jks  

The keystore.jks is the one used by tomcat so the path to it should also be specified in this command.

This steps are taken from Microsoft's documentation on securing SQL Server connections:

https://docs.microsoft.com/en-us/sql/connect/jdbc/connecting-with-ssl-encryption?view=sql-server-ver15

https://docs.microsoft.com/en-us/sql/connect/jdbc/configuring-the-client-for-ssl-encryption?view=sql-server-ver15#importing-the-server-certificate-to-trust-store



2.4 - Configure Authentication Methods

Configure the authentication method(s) that will be used by the extension. Change the properties in config.yml file (located in WEB-INF/classes) under the authentication section:

authentication:
  methods:
    - kerberos
	- tableauserver
	- inmemory
	- ldap
    - saml
    - openid
Property SectionProperty nameCurrent ValueDescription
authenticationmethods

- kerberos

- tableauserver

- inmemory

- ldap

- saml

- openid

The list of authentication methods to be used by the extension. The order in which the methods are listed is the order in which the authentication providers will be registered in the application.

If you want just one authentication method to be used you can accomplish that by comment/delete the other lines.

The following values are allowed:

  • kerberos
  • tableauserver
  • inmemory
  • ldap
  • saml
  • openid

By default you should only have one authentication type active and all other commented. If multiple authentication types are active Write-Back will search for the user sequentially on all of them. When using SSO methods like Kerberos, SAML or OpenID you should always configure a callback method that requires the user to enter its credentials, like inmemoryor ldap.


  1. Configure the necessary properties for the enabled authentication methods.


Configure Kerberos

  1. To configure Kerberos authentication, change the properties in the config.yml file (located in WEB-INF/classes) under the authentication.kerberos section and add the different options to your site files (located in WEB-INF/classes/sites, you must have at least the default one) under authenticationOptions.kerberos section. This is a similar configuration to what you would find on the Tableau Server configuration.

    Config.ymlA site file
    authentication:
      methods:
    	- kerberos
    	(...)
    
      kerberos:
        service-principal: HTTP/mycompany.com
        key-tab-location: c:/mycompany.com.keytab
        ad-domain: MYCOMPANY.COM
        ad-server: ldap://kerberos-server.mycompany.com/
        
    authenticationOptions:
    	kerberos:
    		ldapSearchBase: cn=Users,dc=mycompany,dc=com
        	ldapSearchFilter: (userPrincipalName={0})
    Property SectionProperty nameCurrent ValueConfig fileDescription/
    authentication

    kerberos

    service-principalHTTP/mycompany.comconfig.ymlService principal to access Active Directory and search/validate credentials. The keytab must contain the key for this principal.
    key-tab-locationc:/mycompany.com.keytabconfig.ymlThe file system location of the Kerberos keytab file in the extension server.
    ad-domain

    MYCOMPANY.COM

    config.ymlThe Active Directory domain name.
    ad-server

    ldap://kerberos-server.mycompany.com/

    config.ymlThe Active Directory/LDAP url.
    ldap-search-base

    cn=Users,dc=mycompany,dc=com

    a site fileThe LDAP root DN to apply the search filter.
    ldap-search-filter(userPrincipalName={0})a site fileThe LDAP filter string to search for the user being authenticated. 


  1. Configure browsers for Spnego Negotiation. This configuration is needed to use Kerberos authentication for Tableau Server on the user browser. To configure Spnego Negotiation, check the following guide: link.


When using Kerberos as an authentication option, it is mandatory at the current state, to include another authentication option, since Tableau Desktop does not support Kerberos auth. If you are using Kerberos with Active Directory, you can also set up the LDAP authentication option together with Kerberos, as a fall back for when Kerberos fails. You can choose any other authentication option to pair it with Kerberos that is not also an SSO.


Configure Tableau Server URL

  1. To configure Tableau Server authentication the URL for the server must be provided in the config.yml file, under authentication.tableau-server, in the following format: https://MY-SERVER/api/3.4 where "tableau-server-name" is your Tableau Server URL and "3.4" should be replaced with the proper API version of your Tableau Server. If you have different sites you need to authenticate to, you can create different site files (located in WEB-INF/classes/sites), one for each site, and specify the site under authenticationOptions.tableauServer section. 
    1. To check the API version refer to the chart in the following page: https://onlinehelp.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm

      Config.ymlSite file
      authentication:
        methods:
      	- tableauserver
      	(...)
      
        tableau-server:
          api-url: https://MY-SERVER/api/3.4
      authenticationOptions:
      	tableauServer:
      		site: 



      Tableau Server Auth Warning

      When using this type of configuration, it is strongly recommended that you use your Tableau Server over HTTPS as this is an authentication method and username and password are sent, as plain text, through the API call to the Tableau Server. HTTPS makes it so that the request is encrypted and secure.

      Property SectionProperty nameCurrent ValueConfig FileDescription
      authentication

      tableau-server

      api-urlhttps://MY-SERVER/api/3.4config.ymlURL of the Tableau Server with its API version
      siteemptya site fileThis is a optional setting, here you specify the site you are trying to authenticate to. If none is written then it will authenticate to the default.

Configure In-memory

Allows configuring the uses and passwords directly on the extension but it should be noted that it is volatile and should be used mostly in case of product trial.

To configure in-memory authentication, change the properties in a site file (located in WEB-INF/classes/sites) under the authentication.inMemory section. You can specify as many users as you like.

config.ymlA site file
authentication:
  methods:
	- inmemory
	(...)
  
authenticationOptions:
  inMemory:
	users:
      - username: user1
      	password: password
	  - username: user2
        password: password
	  - username: user3
        password: password
  



Property SectionConfig FileProperty nameCurrent ValueDescription
authenticationOptions:
  inMemory:
	users:
  



a site fileusername

user1

Username for user1
password

password

Password for user1
username

user2

Username for user2
passwordpasswordPassword for user2
usernameuser3Username for user3
passwordpasswordPassword for user3


Configure LDAP/Active Directory

Allows configuring the use of an LDAP server including an Active Directory instance. 

To configure LDAP access and authentication, change the properties in config.yml file (located in WEB-INF/classes) under the authentication.ldap section and add the different options to your site files (located in WEB-INF/classes/sites, you must have at least the default one) under authenticationOptions.ldap section.

Example properties:

Config.ymlA site file
authentication:
  methods:
	- ldap
	(...)

  ldap:
    server-url: ldap://13.80.28.55:389
authenticationOptions:
  ldap:
    searchBase: OU=writeback,DC=xpwb,DC=com
    searchFilter: (cn={0})
    principalDn: CN=writeback extension,OU=writeback,DC=xpwb,DC=com
    principalPassword: secret
Property SectionProperty nameCurrent ValueDescription
authenticationldapserver-url

ldap://13.80.28.55:389

The LDAP server url. You can also use ldaps:// if the ldap is configured for ssl.
searchBase

OU=writeback,DC=xpwb,DC=com

The LDAP root DN to apply the search filter.
searchFilter(cn={0})The LDAP filter string to search for the user being authenticated. Please ensure that the search filter is enclosed in parenthesis.
principalDnCN=writeback extension,OU=writeback,DC=xpwb,DC=comThe LDAP user that will bind the other users to validate the authentication. The principal DN should be the complete DN
principalPasswordsecretThe password for the principalDn.

More on search filter

The search filter must be encapsulated in parenthesis, i.e., (sAMAaccountName={0}). It is also possible to define more complex search filters like so: (&(|(cn={0})(sAMAccountName={0}))(objectCategory=CN=Person,CN=Schema,CN=Configuration,DC=xpwb,DC=com). Explanation: Users that  have that specific object category and belong to the defined 

More on principal DN

Regarding the principal, it is required to provide its full DN. This way the configuration is flexible, i.e., you can search for users that are not on the same search base of the principal if you wish to. Example of full principalDn: CN=writeback extension,OU=writeback,DC=xpwb,DC=com


Using LDAPS

In order to use LDAPS with Write-Back you need to add the certificate used for SSL in your ldap to the java trusted certificates (the java that is used to run the Tomcat). You can do this with keytool. To do so:

  • Go to your java_directory/jre/lib/security
  • Run the command: 

    keytool -import -alias AN_ALIAS -keystore ./cacerts -file CERT_FILE

    Where the AN_ALIAS should be unique to the keystore, e.g: ldaps_cert, and the CERT_FILE is the path to the certificate file of your ldap.

  • If it is a self-signed certificate or a internal CA issued certificate, you just need to write yes when asked "Trus this certificate"

This should be all you need to do in order to enable LDAPS with WriteBack 

Other SSO Methods

When using below SSO methods as an authentication methods remember that you must also configure another method to use with Tableau Desktop. You can choose one of inmemory authentication or ldap authentication (tableau server auth does not work with SAML or OpenID Connect when one of these is enabled in as an authentication method for Tableau Server).

When using these methods, Write-Back proceeds to request the authentication from the Identity Providers, as such, we recommend you firstly authenticate with it. This will probably already be done, if you are using the same method to authenticate with Tableau.

When using these methods with Tableau Online you will probably have two separate domains for where the Write-Back is deployed and the Tableau domain. This means that the token we generated will not be shared with Tableau Online. To prevent this from happening we added a new configurable property.


Config.yml
security:
  cors:
    tableau-online-usage: true


This tableau-online-usage will enabled the browser to share the authentication token with Write-Back when using Tableau Online. If you are using Tableau Server and it is in the same domain as Write-Back then you probably do not need to worry about this property.

SAML

SAML authentication is also an option to authenticate users using the extension with Tableau Server. In order to setup SAML with Write-Back there will be mainly two things you need to do.

  1. Create a Trust Relationship with your IDP
  2. NameID should be formated for

    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

In order for you to create the Trust Relationship for Write-Back, firstly download the metadata.xml from your IDP and store it under {tomcat-installation-path}/webapps/twbe/WEB-INF/classes/saml. Regarding the IDP metadata, please make sure if it is able to accept the binding HTTP-Post for the single sign on service, since this is the only option available to work with Tableau from an extension perspective. You can do this by opening the IDP metadata file and localize the words (with CTRL+F for instance) 

SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

This needs to be an available binding for SAML to work.


After that change the property idp-file-name to match the file name you just place in the folder and restart the webapp. Later, to create the Trust Relatioship on the IDP you will need our metadata information. To do so you need to acess the http(s)://domain/webapp/saml/metadata endpoint that will download a writeback_metadata.xml file which you can then import it in your IdP. Here you can find our entityID com:writeback:sp and our ACS URL.

The properties you can customize are in the config.yml file located in the {tomcat-installation-path}/webapps/twbe/WEB-INF/classes folder. You just need to make sure the idp-file-name matches the file you placed in the SAML folder:

Config.yml
authentication:
  methods:
	- saml
	(...)

  saml:
    idp-file-name: idp.xml
Property SectionProperty nameValue exampleDescription
authentication

samlidp-file-nameidp.xmlThe file name of the IDP metadata for the Write-Back to load. You need to store this file under {tomcat-installation-path}/webapps/twbe/WEB-INF/classes/saml

Currently, we are not validating the signature of metadata and SAMLResponse. 

Currently we only support one Identity Provider, as in we only configure one IDP in Write-Back (we are not doing Discovery of IDPs)

When using SAML as an authentication option, it is mandatory at the current state, to include another authentication option, since Tableau Desktop does not support SAML auth redirects. You can also set up the LDAP authentication option together with SAML, as a fall back for when SAML fails/is used in Tableau Desktop. You can choose any other authentication option to pair it with SAML that is not also an SSO.

OpenID Connect

To use OpenID Connect as an authentication option we you need the following properties configured on the identity provider:

  • grant access to the openid and email scope (we use the email to audit the records in the historical_audit database)
  • the token endpoint authentication method is set to basic.
  • the callback URL should be: https://yourdomain.com/twbe/openid_connect_login

We are also assuming that the identity provider is configured for:

  • support code, token, and id_token as response type options
  • support for pairwise and public subject types (you can choose any to use with Write-Back)
  • support for the scopes required above

After this, within Write-Back you will have to provide some properties in the config.yml file located in the {tomcat-installation-path}/webapps/twbe/WEB-INF/classes folder:

authentication:
  methods:
	- openid
	(...)

  openid:
    issuer: https://issuer
    jwks-url: https://issuer/authorizationendpoint/keys
    authentication-url: https://issuer/authorizationendpoint
    token-request-url: https://issuer/token
    user-info-url: https://issuer/userinfo
    client-id: id (Generated when registering the Write-Back as a client)
    client-key: key (Generated when registering the Write-Back as a client)

Tip

You can find the information above by taking a look at the /.well-known/openid-configuration which is usually implemented in your idp.


2.5 - Configure Session Token

Configure the information used to generate and validate the authorization token created after authentication.

  1. Change the application name property in application.yml file (located in WEB-INF/classes):

    spring:
      application:
        name: tableau-extension
    Property SectionProperty nameCurrent ValueDescription
    springapplicationname

    tableau-extension

    Included in the claims when generating the token. Used to validate the token in any request.


    1. Change the properties in config.yml file (located in WEB-INF/classes) under the jwt section:

      jwt:
        server-host: kerberos-server.mycompany.com
        secret-key: SecretKeyToGenerateJWTs
        algorithm: HS512
      Property SectionProperty nameCurrent ValueDescription
      jwtserver-host

      my-server.mycompany.com

      Included in the claims when generating the token. Used to validate the token in any request.
      secret-key

      SecretKeyToGenerateJWTs

      The secret key to sign the token.
      algorithm

      HS512

      The signature algorithm used to sign the token.

      The following value is allowed:

      • NONE - no digital signature or MAC performed
        • HS256 - HMAC using SHA-256
          • HS384 - HMAC using SHA-384
          • HS512 - HMAC using SHA-512
          • RS256 - RSASSA-PKCS-v1_5 using SHA-256
          • RS384 - RSASSA-PKCS-v1_5 using SHA-384
          • RS512 - RSASSA-PKCS-v1_5 using SHA-512
          • ES256 - ECDSA using P-256 and SHA-256
          • ES384 - ECDSA using P-384 and SHA-384
          • ES512 - ECDSA using P-256 and SHA-512
          • PS256 - RSASSA-PSS using SHA-256 and MGF1 with SHA-256
          • PS384 - RSASSA-PSS using SHA-384 and MGF1 with SHA-384
          • PS512 - RSASSA-PSS using SHA-512 and MGF1 with SHA-512
      expiration-time

      (Optional)

      The expiration time of the generated token, specified in minutes.

      If the property is not defined, the default expiration time is used (60 minutes).

2.6 - Configure Logging

The log properties can be configured in the log4j.properties file, located on WEB-INF\classes:

Property nameCurrent ValueDescription

log4j.rootLogger

ERROR, stdout, file

The first value in comma-separated list is the root logging level value.
log4j.appender.file
log4j.appender.file=org.apache.log4j.RollingFileAppender
The appender FILE is defined as org.apache.log4j.FileAppender.
log4j.appender.file.File
${log}/logger
It writes to a file named logger.log located in the log directory

2.7 - Configure Licenses

To use the extension is necessary to have a license key. If you have one, you must add it at the end of the config.yml file, located at {tomcat dir}\webapps\twbe\WEB-INF\classes folder.

license:
       licence-key: {key generated}

2.8 - Deploy War File

  1. After performing all the configurations:
    1. Restart tomcat server/service 

(Optional) To be able to update the war file without restarting, change <Context reloadable="true"> in context.xml.

2.9 - Validate success of Installation

To validate if the connection was successful you should do these steps:

  1. Open the browser;
    1. Access the tomcat URL followed by the war name and endpoint name in the end (e.g. https://your-server:8143/<war name>/site/default);
      1. A page showing Looking for Extension Configuration should show up
      2. It is also possible to check if the connection was done successfully or not in the log files in <tomcat dir>/logs/*
        1. Both logs for the server life-cycle and the extensions workflow will be in here, allowing for understanding of possible errors.


The configuration can also be edited after doing the deploy. If Tomcat is running, the .war file will be extracted automatically and in the extracted folder it is also possible do go to WEB-INF/classes/config.yml. Changes can be made there but will only be available after restarting the server.

2.10 - Configuring the external url

To make Write-Back more flexible and ensure proper redirects we have the external-url parameter on the config.yml. This parameter as the name says is used to generate any URLs inside the Write-Back application and should be set based on your network / proxy configuration. This is a mandatory parameter, even if you are not using a proxy, just to guarantee that the redirect works properly. 

external-url:
  domain: http(s)://domainintrex.com
Property SectionProperty NameDescription
external-urldomain

Here you should place the url that is also in the .trex file without describing the context path and no ending forward slash.


Example:

URL In TrexDomain property
https://domain.com/twbe/site/defaulthttps://domain.com
http://domain.com:768/twbe/site/cahttp://domain.com:768


3 - Configuring Write-Back Themes

Write-Back allows customizing its look and feel. This means that now you can decouple the brand part of Write-Back and customize colors and logos in order to perfectly fit into your dashboard. Find below more details on how to do it. The colors need to be in an hexadecimal (HEX) code.

All the configurations and properties available can be specified differently per Write-Back site, meaning each site can have its own theme. For each site you will fill the information on the corresponding yaml file located on WEB-INF/classes/sites folder. On the instructions below default.yml is used as an example. 

The customization of themes does not need to include all the parameters, although the Color Picker Options (3.1) are mandatory to be present.

3.1 - Color Picker Options (mandatory)

You can customize the Add Data Button by changing its color, size and label in order to match your dashboard. The list of colors that will appear on the color picker when configuring the extension for the button are listed in the default.yml therefore you need to make this option available in order for the widget configuration to be fully functional. 

So, to allow the power use to choose the colors they need to be made available in the default.yml file.

Here is how:

  • In your default.yml file add a new section called themeProperties (if it does not already exists)
(...)
themeProperties:
  • Add a dashboardButtonProperties section as a child of themeProperties.
(...)
themeProperties:
	dashboardButtonProperties:
  • Add a list of colorOptions for the power user to choose from when configuring the widget.
  • We suggest having no more than 6 colors list in order to keep the UI clean.
  • Additionally you can change any of these colors.


(...)
themeProperties:
	dashboardButtonProperties:
		colorOptions:
			- colorOption: '#00A2AA'
      		- colorOption: '#D0021B'
      		- colorOption: '#F5A623'
      		- colorOption: '#F8E71C'
      		- colorOption: '#8B572A'
      		- colorOption: '#7ED321'

3.2 - Theme Customization Example

Next, you can see an example of the 3 screens with custom colors. Below, you'll find the legend for the numbers on the images pointing to the colors that will be affected by that property.

Finally, you have the block form the .yml file you need to use this specific color theme. You can see that there is nothing specified in the logo and header title properties, when nothing is specified, Write-Back uses the default properties.


Legend:


Theme Config
  labelsProperties:
      titleColor: '#362415'
      subTitleColor: '#362415'
      labelColor: '#604c4c'
      inputColor: '#604c4c'
  pillsProperties:
      color: '#0b421a'
      fadedColor: '#0b421a'
  errorsProperties:
      color: '#EB4454'
  buttonsProperties:
      color: '#0b421a'
  backgroundsProperties:
      highlightColor: '#eac784'
  headerProperties:
      logoPath:
      title:

3.2.1 - Label and Title Colors

You can customize the color of the text for labels and titles that display information not only to the power user but also to the end-users. 

There are four types of text in Write-Back : 

3.2.1.1 - Title

Each major section in the write-back has an associated title in bold.

3.2.1.2 - Sub Title

Minor sections or extra information under title definitions.

3.2.1.3 - Label

Text information or placeholders most of the time representing labels of buttons or input placeholders.

3.2.1.4 - Input

Any user input such as numeric, text, table cells, dates, etc.

3.2.2 - Pills Colors

In Write-Back, all fields that can be used in the configuration are represented by pills. You can customize the color of these pills.

There are two types of states for pills in Write-Back:

3.2.1.3 - Default Pill

Default pill that is represented in the configuration panel and in the marks selected at standard and tabular panels.

3.2.1.3 - Faded Pill

Timeline pills and not selected marks in editing mode.

3.2.3 - Errors Color

In Write-Back when something goes wrong, an error is shown. You can customize the color of these errors. This color will be in text messages, some borders, pills and table cells as well.

3.2.4 - Buttons Colors

In Write-Back, across all screens, there are some buttons that allow the users to execute some operations, such as submit a configuration, insert data, etc. 

3.2.5 - Backgrounds Color

In Write-Back, across all screens, there are some sections with a different background color, such as the section where source fields are located, on the configuration screen, the timeline, etc. 

3.2.6 - Header 

In Write-Back, across all screens, there is a header where we can find an image and text. You can now customize both the image and the title that is shown.

3.2.1.3 - Logo Path

Choose your company logo , to do this you only need to specific the path "images/<your-logo.png> and paste your image inside of <instalation-path>\webapps\twbe\WEB-INF\

classes\public\images folder.

3.2.1.3 - Title

Customize the header title of every Write-Back Screen.


4 - Configure Tableau Server to Use Extension

To start using the extension with Tableau Server it is necessary to grant permission for the extension to run when dragged to a dashboard.

4.1 - Grant permission to run in Tableau Server

After logging in Tableau Server with an administrator role account, consider the following instructions:

  1. Go to Settings > Extensions.
    1. Under Enable Specific Extensions, add the URL of the extension.
      1. Choose to Allow or Deny the extension of Full Data Access.
      2. Choose to Show or Hide the User Prompts. (This prompt shows up when the extension is opened the first time on a dashboard)

Source: Tableau Documentation

4.2 - Full Data Access

"Full data access is access to the underlying data in the view, not just the summary or aggregated data. Full data access also includes information about the data sources, such as the names of the connection, fields, and tables. In most cases, if you are adding an extension to the safe list so that it can run, you will also want to allow the extension to have access to full data if the extension requires it."

4.3 - User Prompts

"Users see the prompts by default when they are adding an extension to a dashboard, or when they are interacting with a view that has an extension. The prompt tells users details about the extension and whether the extension has access to full data. The prompt gives users the ability to allow or deny the extension from running. You can hide this prompt from users, allowing the extension to run immediately."


4 - Getting a trex file

To use the extension you need access to a trex file that points to the URL where the extension is running. Extension user that create new dashboards will require having this file so it needs to be distributed.

To generate the file open this example and change the server location to your own:

   <source-location>
      <url>https://my_company_server:port/twbe</url>
    </source-location>

https://my_company_server:port/twbe should be replaced by your own URL and port (as per this manual it should be 8143 but will depend on your setup).

Here is a complete trex (manifest) file: Write-Back.trex. You just have to change the URL and port as mentioned before.

5 - Testing the Deployment

  • Desktop
    • Open tableau desktop
      • Create a sheet with any chart
        • Create a dashboard and add the sheet previously created
        • In objects, select Extension and drag it to the dashboard
        • Select My Extension, go to <project-dir>/main/resources/public/manifest, select the trex file and open it
        • If everything is ok, you should log in and then get a pop-up will show up with the configurations menu
        • Configure the extension
          • Choose the sheet providing a dataset name and configure one field. 
          • Submit the form and the window should close
      • Server
        • Publish the dashboard from Desktop to Tableau Server
        • Open the Dashboard on the server
        • If everything is ok you should be able to click on a mark form the chart and the submission screen from the extension will pop-up
        • Place data on the field and submit, the window should close.


6 - External access requirements

  • Proxy such as Apache (optional)
    • Needed for external access.
      • Domain name (URL) for the extension. It is required to be able to call the extension based on the name instead of IP, this name will be shown to the Desktop inside the .trex file.
      • SSL Certificate from a Certificate Authority, to be able to run the extension over HTTPS. Similar to Tableau Server and depends on the previous pre-requisite as the certificate mentions the URL. 


  • No labels