Tableau provides a solution for embedding content into Salesforce, called Sparkler. Sparkler is a web app, which lives on its own server, that sits between Salesforce and your Tableau Server. Sparkler allows for single sign on using Trusted Tickets, so that users logged into Salesforce are automatically logged into your Tableau Server. It also makes it easier to embed tableau dashboards into various pages within Salesforce. Tableau provides some documentation on how to get Sparkler setup, but it's a manual process. This project aims to automate as much as possible, and make it easier to get started using Tableau, Sparkler, and Salesforce.
You'll need to have the following, in order to complete the setup
- A Salesforce System Administrator login, in order to add Sparkler as a connected app in Salesforce
- Access to TSM on your Tableau Server, as well as being able to perform a server restart
- Either of the following:
- AWS account with permission to spin up new instances, and an AWS SSL certificate
- Linux server with a SSL certificate (not self-signed)
The first thing to do, is create a connected app in Salesforce. Login to Salesforce and goto the Setup app, using the dropdown menu at the top right of the screen.
Using the left navigation search bar, navigate to the App Manager page and click on the New Connected App button.
On the next page, you'll need to add a few details about this new connected app. Fill in the Connected App name, API name, and contact email with whatever values you like. Just know that whatever app name you choose, will be needed when embedding later on. The other important sections are for API and Canvas App Settings.
For the API section, you need to add a callback URL witch will follow this format: https://<your-sparkler-server>/sparkler/keepAlive. You will also need to add Access your basic information(id, profile, email, address, phone) to the list of Selected OAuth Scopes.
For the Canvas App Settings, you should make sure the Canvas option is checked, and the Access Method is set to Signed Request(POST). The Canvas App URL should match the following format: https://<your-sparkler-server>/sparkler/sfdc/canvas. Lastly, make sure Chatter Feed, Publisher, Visualforce Page are in the Selected list of Locations. Once these settings are entered, you can click save.
Next, we need to add some permission profiles to our connected app. Use the search navigation to goto the Connected Apps page and click the edit button next to your sparkler app. Change the Permitted Users setting to Admin approved users are pre-authorized and click save.
This should refresh the page, and you'll be back to the list of all apps. Click on the name of your sparkler app (blue link), and you should now be able to click on Manage Profiles. Add at least one profile, like System Administrator.
At this point, everything is setup and you just need to get the consumer secret of your app. Use the search navigation to get back to the App Manager page and click on your Sparkler app to view the details. Click on the button to show you the consumer secret and make sure to copy this string of text, as you will need this for setting up sparkler.
This option is applicable if your organization has its own servers (hyper-v, vmware, physical machines, etc) and you want to host the Sparkler web app. In this case, you can use the setup.sh bash script to automate the installation and configuration of your sparkler server. The bash script should work on any linux OS, that leverages YUM as a package manager and systemd for service management. The script was testing on Amazon Linux 2, which is similar to CentOS and RedHat.
To run the setup, copy or download the setup.sh to the server you want to run Sparkler on, which must be a linux box (CentOS/RedHat preferred). Also, make sure the setup.sh file has execute permissions (chmod 550). You will need these 2 additional files on your Sparkler server:
- config - Simple file that gets sourced by setup.sh, so that we know where to download Tomcat and Sparkler from. See the example file here
- sparkler.xml - This will need to be configured to match your Tableau and Salesforce environments. See the template here for more details on what options need to be set here.
Assuming you copied all three files (setup.sh, config, & sparkler.xml) to the Sparkler server's /tmp directory, you can run the setup like this:
sudo ./setup.sh "/tmp/config" "/tmp/sparkler.xml"
This should download/install Java and Tomcat, configure tomcat to run as a service (so it starts automatically if the server restarts), download/configure/deploy the sparkler web app. Since this script was testing on Amazon Linux 2, your mileage may vary on other operating systems, but you should be able to tweak the script as needed for different distros.
The only thing not done by this script, is to configure Sparkler with SSL. In AWS we use a Load Balancer with SSL termination to achieve this, but when deploying on your own server you will need to setup SSL before using Sparkler. We discourage the use of self-signed SSL certificates, as they will show a warning prompt when used and will not work with the Salesforce mobile app. For help setting up SSL with tomcat, see their official documentation to import the certificate. You will also need to adjust Tomcat's server.xml configuration file, found at /opt/tomcat/conf/server.xml. There should be a section (commented out) for enabling SSL on port 8443, just remove the <!-- and --> above/below the Connector, and restart tomcat. Now you should be able to access the sparkler app via SSL on port 8443.
This option is applicable if your organization leverages AWS as a hosting platform. In this case, you can use the cloudformation template to spin up a new EC2 instance and automatically install/setup Sparkler. Before using Cloudformation, you need to make sure you have an SSL Certificate available to use. Since Salesforce.com uses HTTPS for their site, any communication to Sparkler (and Tableau Server) must also be over HTTPS. If you've never created an SSL Certificate before, you can see this link on how to create SSL certificates using AWS Certificate Manager. You will need the ARN from your SSL Certificate, to pass as a parameter for the Cloudformation template.
To use the Cloudformation template, search the AWS Console for Cloudformation and use the left navigation to get to the Stacks page. Click the button to Create Stack - with new resources. Step 1 is just to download the template file, upload it using the Choose File button, and click the next button.
The next page is just for entering your parameters. The table below, outlines what should be used for each parameter:
| Parameter | Type | Description |
|---|---|---|
| VPC | AWS | Select the VPC you want to deploy to |
| Instance Type | AWS | Instance type for the sparkler server, the default should be fine |
| Primary Subnet | AWS | Choose a subnet, in which to deploy the Sparker server |
| Secondary Subnet | AWS | Choose a subnet from a different availability zone. The load balancer requires 1 subnet from each AZ |
| Security Groups | AWS | Specify which security groups to apply to the EC2 instance. Ports 80 and 443 should be allowed for inbound HTTP/HTTPS traffic. |
| SSL Certificate ARN | AWS | Copy/paste the ARN of your SSL Certificate, from AWS Certificate Manager |
| Key Pair | AWS | Key pairs are required to creating any EC2 instance, so that you can actually connect to it via SSH |
| Consumer Secret | Salesforce | Copy/Paste the consumer secret from your Salesforce Connected App |
| User Identifier Field | Salesforce | Select which method should be used to map Salesforce users to Tableau users |
| Allowed Email Domains | Salesforce | If selecting signedIdentity as the User Identifier Field, you must specify the email domain(s) to allow (ex. @company.com |
| Tableau Server Host | Tableau | Name or IP address of your Tableau Server (do not include https://) |
| Tableau Server SSL | Tableau | Does your end users access Tableau Server over SSL? |
| Tableau Server Port | Tableau | Port of your Tableau Server (usually 443 for SSL) |
| Tableau User for Testing | Tableau | Any Tableau User, that we can use to verify SSO is working |
| Use Trusted Tickets | Tableau | Should we use Trusted Tickets to enable SSO? |
| Enable Sparkler Status Page | Tableau | Should we enable the status page for Sparker? Mark yes for testing, but disable this in production. |
The next page can be left as is, just click the next button. On the last page, check the blue box at the bottom and then click on the orange Create Stack button.
Once started, the events tab should show you the progress of your cloudformation stack. You should see a green checkmark next to the stack name, once the process is complete.
You can get the Sparkler server's public IP from the Outputs tab, which can be used for setting up Trusted Tickets on your Tableau Server.
Tableau provides instructions for how to setup trusted ticket authentication, which can be found here. You'll just need the IP of your Sparkler server, in order to add it as a trusted ip on your Tableau Server. Once you've configured Tableau Server for Trusted Tickets from Sparkler, you should check Sparkler's status page at https://<sparkler-server>/sparkler/status
- This project is not meant to replace the official documentation on Sparkler
- For more details on the installation process and settings to tweak, please refer to the sparkler documentation
The Cloudformation template creates the following resources:
- EC2 Instance - Used to host the Sparkler web app
- Application Load Balancer - Provides SSL termination, and directing requests to the tomcat port
- Listener for HTTP/80 - Listens for HTTP traffic, and redirects to HTTPS
- Listener for HTTPS/443 - Redirects HTTPS traffic to the tomcat web app
- Load Balancer Target Group - Defines what instances are available
- IAM Role - Used to define what the EC2 instance is permissioned to do. The policy equates to the following named policies:
- ElasticLoadBalancingReadOnly
- ElasticLoadBalancingFullAccess
- ResourceGroupsandTagEditorReadOnlyAccess
- ResourceGroupsandTagEditorFullAccess
- AmazonEC2SpotFleetTaggingRole
- AmazonEC2FullAccess