Here are links to documentation for Zuar's other products:

• Mitto
• Rapid Portal
• Custom Portal

More content is available on Zuar's blog.

Join the Zuar community and discuss WAF!

What is the Zuar Web Application Firewall?

The Zuar Web Application Firewall (ZWAF) is a software based web application firewall. It handles all security (authorization and authentication) aspects for all of Zuar's products:

• Mitto
• Rapid Portal
• Custom Portal

Architecture

The WAF was developed with web application best practices in mind:

• Web Server - Acts as a gateway to your application server and serves up static files (images, JavaScript, CSS, etc). Also handles routing of data to 1 or more application servers.
• Application Server - Becomes IdP for your web server. Handles authentication to avoid security risks.

WAF can be configured to use Tableau Server/Online for authentication.

Tableau APIs

When the WAF is configured with Tableau Server/Online, many of the Tableau APIs become available to authenticated users:

• Tableau JavaScript API
• Tableau REST API
• Tableau Trusted Authentication API

Tableau Configuration

Configuring a Zuar Portal to use Tableau Server/Online is done via the Portal's env file:

• TABLEAU_SERVER_URL - This is the URL of the Tableau Server/Online (e.g. https://tableau.zuar.com or https://us-east-1.online.tableau.com/).
• TABLEAU_SERVER_SITE - This is the site of the Tableau Server/Online.
• TABLEAU_SERVER_USERNAME - (Optional) This is the username of a Tableau Server server administrator account. This is used for Tableau REST API impersonation.
• TABLEAU_SERVER_PASSWORD - (Optional) This is the password of a Tableau Server server administrator account. This is used for Tableau REST API impersonation.

Tableau Server/Online Server and Site

What is my Tableau Server/Online URL?

What is my Tableau Server/Online site?

If you are using the Default site you won't see the word site in your Tableau URL. For example:

The Zuar Web Application Firewall (WAF)  architecture consists of a standard web server, an authentication micro service, and by default a PostgreSQL database.  The design is modular, with well defined interfaces among the components, so both the authentication service and PostgreSQL may be replaced with suitably similar technology.

Web Server

The web server is the industry-standard, open-source NGINX server with additional embedded modules to handle aspects of authorization. The entire authentication validation mechanism runs in the context of the web server itself, resulting in optimal performance.

Authentication Micro Service

The authentication micro service (auth service) only handles requests specifically for login and logout and is responsible validating the user and assigning user permissions.

Users can be authenticated in one of several ways:

1. Against the local database
2. Against an optionally configured Tableau Server/Online.
3. Using a custom built authentication module.

If a given user is not found in the local database, then the configured Tableau Server is tried. A common deployment is to have no local users so that Tableau Server is used exclusively for authentication. To use the SAML terminology, the Tableau Server acts as an Identity Provider (IdP).

User information - including authorization information, but NOT their password - is stored in a JSON Web Token (JWT). The JWTs are digitally signed with the HMAC SHA256 encryption algorithm (HS256) and are validated both for time and originating IP address.

The default portal configuration proxies all requests to the /api URI directly to the configured Tableau Server / Tableau Online. This results in the Tableau REST API being accessible to the front-end in a secure fashion that is not possible without the portal. Front-end, JavaScript code may make calls directly to the Tableau REST API without having to build an intermediary API as is normally required.

Workflow

Here is the workflow when a user accesses a WAF for the first time, where the WAF has the default configuration using Tableau Server as the IdP.

• User accesses the portal URL with a browser, say https://example.zuar.com
• Since the user has never logged in, they don't yet have a JWT so they are automatically redirected to the login page at https://example.zuar.com/login.
• This URL is proxied by the web server to the auth service which responds to the GET request with a standard login form.
• The user inputs their username and password which is submitted back to https://example.zuar.com/login as a POST request.
• The auth service takes the information and compares it against its local users.
  If the user is not found - the normal case - then the information is sent to Tableau Server/Online for validation.
• Assuming the user information is valid, then Tableau Server responds to the auth request with general user information, e.g. display name, user id, email, etc.
• Once a successful response from Tableau Server is received, the auth service generates a JWT and includes the information it received fromTableau Server in the payload. The payload information can be used by downstream services - for example, to display the full name of the logged in user.
• The auth service responds with a redirect (302 Found) back to the original location with the JWT sent as a cookie in the response.
• The user is automatically redirected back to https://example.zuar.com but now has a valid JWT so the web server validates the request handle and returns the default web application.

Deployment

The web server, auth server, and PostgreSQL database are all deployed using Docker.
Each component is a separate Docker container with all containers orchestrated by docker-compose.

There is one docker-compose.yaml file that controls all containers and
an environment file for sensitive information as per 12factor methodology.

The NGINX configuration are mounted as volumes so they may be customized as desired.

Security

• Built using proven, open-source technology for base request handling.
• Design follows all OWASP security guidelines
• All passwords are stored using a PBKDF2 SHA512 one-way hash. At no point are passwords stored either in the clear or using reversible encryption.
• Built-in ModSecurity.

The portal acts as a WAF/reverse proxy for Tableau Server as per Tableau guidelines. All external traffic to the application - including to Tableau Server / Tableau Online - can be logged and audited as desired to meet any security requirements. The

Configuration

The Zuar Web Application Firewall (WAF) handles all aspect of authentication and authorization so that the application developer only has to implement their business logic.

This methodology is particularly useful when building an application utilizing Tableau for embedded analytics.

Since the WAF is designed to be starting point for third-party applications, it is extensively configurable. All standard NGINX configuration is available and can be used by the application. The WAF automatically passes all user information from the JWT to downstream application via HTTP headers using a prefix X-Payload-.

The Zuar Web Application Firewall (WAF) can integrate with Salesforce via a Salesforce Canvas App.

Canvas enables you to easily integrate a third-party application in Salesforce.

Canvas Apps and VisualForce Pages

In addition to standard canvas apps, Canvas also lets you expose a canvas app on a Visualforce page. This means you can display a canvas app anywhere you can display a Visualforce page.

The steps below are one time setup on the Salesforce side. These steps require a Salesforce administrator account.

Create a Salesforce Connected App

In the Salesforce UI, click Setup.

Search for "App Manager" and click App Manager.

Click "New Connected App".

Fill out the "New Connected App" form. Not all values are required.

Basic Information

• Connected App Name: (e.g. "Zuar Rapid Portal")
• API Name: (requires all lowercase and underscores) (e.g. "zuar_rapid_portal")
• Contact Email: your Salesforce admin's address

API (Enable OAuth Settings)

• Check Enable OAuth Settings
• Callback URL: https://{rapid_portal_url}/keepAlive (e.g. https://analytics.yourcompany.com/keepAlive)
• Selected OAuth Scopes - Select "Access your basic information (id, profile, email, address, phone)" and click Add
• Check Require Secret for Web Server Flow

Canvas App Settings

IMPORTANT: Depending on your Tableau environment you will use either the signed or vaulted endpoint for the Canvas App URL below. signed is used for Tableau Server with trusted authentication. vaulted is used for Tableau Server without trusted authentication and Tableau Online (which doesn't have trusted authentication). vaulted will prompt the Tableau user for their Tableau password once. If the user's password changes, the user will be prompted again, once.

• Check Canvas
• Canvas App URL: https://{rapid_portal_url}/{signed or vaulted} (e.g. For Tableau Server with trusted authentication use https://analytics.yourcompany.com/signed and for Tableau Online use https://analytics.yourcompany.com/vaulted)
• Access Method: Signed Request (POST)
• Locations: Select "Visualforce Page" and click Add

Click Save.

Back on the "Manage Connected Apps" page, click Manage.

Click "Edit Policies".

OAuth Policies

• Permitted Users - set to "Admin approved users are pre-authorized"

Click Save.

There is a new section named Profiles. Click Manage Profiles.

Check the box next to any profiles you wish to give access to and click Save.

Save the Salesforce Connected App's Consumer Secret

Go back to the App Manager (search "app manager").

Find the newly created Connect App and click View.

In the API (Enable OAuth Settings) section, next to Consumer Secret, click "Click to Reveal".

Save the Connected App's Consumer Secret. This will be needed for configuration on the Zuar Rapid Portal.

Tableau to Salesforce User Mapping

Usernames from Tableau Server/Online must be mapped to information from Salesforce (e.g. username, email).

Tableau Online usernames must be email addresses. Tableau Server usernames can be anything.

Salesforce requires that each username be unique and in the form of an email address. Learn more about Salesforce usernames.

User Mapping Options

• userName
• baseName
• email
• baseEmail

User Mapping Examples

Typically using the email user mapping makes the most sense for Tableau Online user mapping and email or baseEmail makes the most sense for Tableau Server user mapping.

What if None of the User Mappings Fit your Naming Convention?

Let's say your Tableau and Salesforce usernames look like this:

None of the four user mappings work for this Salesforce and Tableau naming convention:

• userName - This would pass john@company.com from Salesforce to john_j_smith on Tableau. Not a match.
• baseName - This would pass john from Salesforce to john_j_smith on Tableau. Not a match.
• email - This would pass johnjs@company.com from Salesforce to john_j_smith on Tableau. Not a match.
• baseEmail - This would pass johnjs from Salesforce to john_j_smith on Tableau. Not a match.

There are a few extra Salesforce steps you can take to solve this:

1. Create a custom field (e.g. tableau_username__c) on your Salesforce User object and for each Tableau user, populate the custom field with that user's corresponding Tableau username. In our example above, we would populate the john@company.com Salesforce user's custom field with john_j_smith.
2. Add a username parameter to the Visualforce APEX code that references this custom field. Read Displaying Field Values in Visualforce.

<apex:page >
<apex:canvasApp applicationName="{canvas_app}"
    maxHeight="infinite"
    width="100%"
    parameters="
    {
        'location': '/z/trusted/{tableau_view_url}',
        'username': '{! $User.tableau_username__c }'
    }" />
</apex:page>

If username exists as a parameter in the Visualforce code, the value of username will be used to map the Salesforce user to the Tableau user.

So for our example above, regardless of the user mapping that is defined on the Portal, the username john_j_smith would be passed to Tableau when john@company loads the Visualforce page.

See more information about the overall process of embedding Tableau into Salesforce here:

Embedding Tableau Into Salesforce using Visualforce | Zuar

Market-leading CRM platform Salesforce.com recently acquired Tableau [https://investor.salesforce.com/press-releases/press-release-details/2019/Salesforce-Signs-Definitive-Agreement-to-Acquire-Tableau/default.aspx] , an innovative data visualization [https://www.zuar.com/blog/data-automation-improve-analysis-productivity/…

Justin FreelsZuar | Blog

Next steps:

1. Share your newly created Salesforce Connected App's Consumer Secret with Zuar either through your account manager or support.
2. Share your Tableau to Salesforce user mapping naming convention with Zuar either through your account manager or support.
3. Zuar will configure your Portal to use the Salesforce Connected App's Consumer Secret and User Mapping.
4. Test the Salesforce Connected App after Zuar performs step 2 above.

Trusted authentication simply means that you have set up a trusted relationship between Tableau Server and one or more web servers. When Tableau Server receives requests from these trusted web servers it assumes that your web server has handled whatever authentication is necessary.

The Zuar WAF can act as the trusted host for Tableau Server and provide single sign on into embedded analytics applications (e.g. Zuar Rapid Portal, Zuar Custom Portal, Salesforce, or your own existing application).

Add the Zuar Portal's Hostname or IP to Tableau Server

For trusted tickets to work your Tableau Server administrator will need to add the hostname or IP Address of your Rapid Portal as a "Trusted Host" under Configuration > User Identity & Access > Trusted Authentication, then save pending changes and restart.

Read Tableau Server documentation: Add Trusted IP Addresses or Host Names to Tableau Server

Tableau Trusted Authentication gotcha:

Static IP addresses are required: The web servers you specify must use static IP addresses, even if you use host names.

This means if you add a hostname to the "Trusted Host" list and the IP behind the hostname changes, trusted authentication will stop working. Tableau Server is essentially hardcoding the IP of the host.

Therefore, best practice is to add IP addresses rather than host names to the Tableau Server "Trusted Host" list.

Next Steps:

1. Test Trusted Authentication in your Zuar Portal

Related Tableau Trusted Authentication Content

Trusted Ticket Authentication with Tableau Server | Zuar

This article describes how Tableau trusted authentication provides Single Sign-On (SSO) for embedded analytics in third-party applications.

Matthew R LaueZuar | Blog

Implementing Trusted Tickets for Tableau Server with NodeJS

This article implements trusted tickets as described in Trusted Ticket Authentication with Tableau Server [https://www.zuar.com/blog/trusted-ticket-authentication-with-tableau-server/]. We’ll build a ticket broker with a simple API called by a front-end that uses the HTML5 <template> tag. The int…

Matthew R LaueZuar | Blog

Alternate Authentication Options

• Tableau Authentication
• Okta Authentication

Docker provides the ability to package and run an application in a loosely isolated environment called a container.

They are orchestrated through Docker Compose.

Compose is a tool for defining and running multi-container Docker applications.

Configuring Docker

All of the Docker Compose configuration (services, networks, etc) is handle via a docker-compose.yaml file.

The default location for the docker-compose.yaml configuration file is the home directory for the user running Docker (e.g. /home/ubuntu/docker-compose.yaml).

Learn more about docker-compose.

Starting and Stopping Docker

Zuar WAF microservices can be individually or collectively started and stopped with Docker Compose:

• Stop the Docker containers with docker-compose down.
• Start the Docker containers with docker-compose up.
• Start the Docker containers in the background docker-compose up -d. This is the standard way to run the Zuar WAF.

Run these commands in the same directory as the docker-compose.yaml (e.g. /home/ubuntu/).

Learn more about docker-compose down and docker-compose up.

Viewing Docker Logs

The logs for the Zuar WAF microservices can be viewed through Docker:

• View all logs for a container running in the background with docker-compose logs -f.
• View the last 100 lines of the logs with docker-compose logs -f --tail=100.
• View the auth container's logs with docker-compose logs -f auth.

Learn more about Docker logs and docker-compose logs.

The env file is normally located in the home directory of the user running Docker. Example: /home/<user>/.env . Any changes to this file will require restarting Docker with:

docker-compose down
docker-compose up -d

Environment Variables

General

• DEBUG
• SECRET
• TOKEN_EXPIRY

Database

• DATABASE_URL
• POSTGRES_USER
• POSTGRES_PASSWORD
• TARGET_DATABASE_URL

Tableau

• TABLEAU_SERVER_URL
• TABLEAU_SERVER_SITE
• TABLEAU_SERVER_USERNAME
• TABLEAU_SERVER_PASSWORD

Related Tableau documentation:

• Tableau Authentication
• Tableau Trusted Authentication

Okta

• OKTA_APP_EMBED_LINK
• OKTA_TOKEN

Related Okta documentation.

Salesforce

• SECRET
• SIGNED_REQUEST_USERNAME

Related Salesforce documentation.

Configuring Nginx

Nginx configuration files are located in the home directory of the user running Docker:

• The main Nginx directory is located at /home/{user}/app/nginx.
• Individual Nginx configuration files are located at /home/{user}/app/nginx/conf.d/.

Learn more about configuring Nginx.

Restarting Nginx

Any changes made to the Nginx configuration files require restarting Nginx.

Restart Nginx through Docker with docker exec zwaf nginx -s reload.

server {
    listen 443 ssl;

    server_name  _;
    root /app/static/;
    resolver 127.0.0.11;

To change the name server you can edit the resolver 127.0.0.11 line to any name server you want (Ex: an internal DNS server like 8.8.8.8). Any changes to this file will require restarting Nginx with docker exec zwaf nginx -s reload

Learn more about setting the DNS resolver using Nginx.

DNS Resolution via Docker

It is possible to add name servers in addition to the existing name server defined in Nginx, via updating the docker-compose YAML file (usually located at: /home/<user>/docker-compose.yaml). To accomplish this, add an extra_hosts block to the zwaf container. Example:

zwaf:
    ...
    extra_hosts:
      - "somehost:162.242.195.82"
      - "otherhost:50.31.209.229"

Any changes made to docker-compose.yaml will require restarting Docker with docker-compose down && docker-compose up -d.

Learn more about adding name servers using Docker.

Users can install their own SSL certificates or have Zuar manage the SSL certificates via LetsEncrypt.

SSL Certificates for Portals

Rapid Portal and Custom Portal are deployed with Docker.

The SSL certificates are mapped into the zwaf microservice. This file mapping is configured in docker-compose.yaml:

zwaf:
    ...
    volumes:
      ...
      - ./server.key:/etc/ssl/private/server.key
      - ./server.crt:/etc/ssl/certs/server.crt
      ...
    ...

In the example above, the SSL certs are composed of two files:

• server.key - This SSL key file is located in the same directory as docker-compose.yaml and is mapped into the zwaf container at /etc/ssl/private/server.key
• server.crt - This SSL crt file is located in the same directory as docker-compose.yaml and is mapped into the zwaf container at /etc/ssl/certs/server.crt

Any updates to the docker-compose.yaml require a restart of the Docker containers.

Docker

Zuar WAF microservices run in Docker [https://www.docker.com/] containers. > Docker provides the ability to package and run an application in a loosely isolated environment called a container. They are orchestrated through Docker Compose [https://docs.docker.com/compose/…

Andy KlierZuar Web Application Firewall

Navigating to this endpoint in your browser as an admin will show you a list of users.

Create User

The create user POST endpoint takes a request object like:

{
  "username": "string",
  "fullname": "string",
  "password": "string",
  "email": "string",
  "admin": false
}

With the swagger endpoint selected, click the Try it out button on the right at the top of the section.

Edit the request object to include the information for the new user, then click Execute to create the user.

Note that creating a user via the authentication API creates a local Portal user. See basic authentication for more information.

List All Users

As mentioned above you can load this endpoint (https://<your-hostname>/auth/users) in your browser. Alternatively you can try the endpoint using the swagger docs. With the swagger endpoint selected click Try it out, then click Execute

Edit/Update User

To edit an existing user, you will first need to get the user's id from the /auth/users endpoint.

In addition to the user's id, the update endpoint expects the following request object:

{
  "username": "string",
  "fullname": "string",
  "password": "string",
  "email": "string",
  "admin": false
}

With the endpoint selected, click Try it out then enter the user's id. Edit the request object with the updated user's information and click Execute.

Promoting a User to Admin

Use the /auth/users endpoint with a GET request to find the specific user's id.

Use the /auth/users/{user_id} endpoint with a PUT request and the specific user's id and the following request object:

{
  "admin": true
}

Delete User

To delete an existing user, you will first need to get the user's id from the /auth/users endpoint.

With the delete endpoint selected, click Try it out and enter the user's id. Clicking Execute will delete the user. You will not get a confirm dialogue.

Base URL

https://{waf_url}/auth

Authentication

The Auth API uses basic authentication for access. See /auth/login endpoint in Swagger for more information.

Authorization

Only admin users have access to the Auth APIs.

Endpoints and Methods

The Auth API has Swagger documentation at /auth/docs. You can see all the API endpoints and test them using the Swagger UI.

Responses

The Auth API returns data in JSON format.

Do this step after Zuar has configured your Portal to integrate with Salesforce.

In Salesforce, search for 'Canvas App Previewer' in the Quick Find search bar.

Click on the newly created Canvas App.

You should see a big JSON object response if the app is configured properly both in Salesforce and on the Zuar Portal side.

Learn more about Salesforce's Canvas App Previewer.

Log into your Zuar Portal and navigate to https://{your_rapid_portal_url}/z/trusted.

If you are not authenticated via Tableau, you'll get a 403 Forbidden error.

If trusted authentication is properly configured, you should see a one time use ticket as an alphanumeric string (e.g. 5NB0HLyVQ7mD61q2phD5Lg==:FMi5vVV4kxGmmf7Rh86_gX66).

If trusted authentication is NOT properly configured, you should will see -1.

Read  more Tableau Server documentation: Ticket Value of -1 Returned from Tableau Server