Configure TLS (SSL)

Connections between Alteryx Analytics Hub (AAH) and your web browser or Alteryx Designer should always be protected by SSL.

Self-signed certificates are automatically generated and installed during AAH installation to keep your platform protected from the moment it starts running. However, self-signed certificates are clumsy to use in the real world and require additional effort on your part on each machine you want to connect to AAH from. 

To simplify your users’ experience, Alteryx recommends you acquire a TLS (SSL) certificate from an SSL Certificate Authority (CA). The CA is an entity that is trusted to sign, issue, distribute, and revoke digital certificates. There are many CAs to choose from. Among the most popular are Network Solutions, Thawte, and GoDaddy. The process of requesting a certificate from a CA is beyond the scope of this article. 

Components of Alteryx Analytics Hub Protected by TLS

Three components of your AAH platform leverage digital certificates to prove their identity and keep communication safe. You can find TLS-related settings for these components spread across two files in the \INSTALL_LOCATION\Alteryx\Alteryx Analytics Hub folder. Please do not edit these files manually. Alteryx provides you with a command-line script (ayxhub.ps1) to make “safe” modifications.

Hub Front End

AAH’s Front-End consists of the website you log into when working with Hub, and the underlying REST endpoints that a developer can call to automate the server. Settings for this component can be found in the ayxserver.https section of the Settings.yml configuration file:

ayxserver:
  ...
  host:
    port: 443
 ...
  https:
    enable: true
    key_location: C:\Program Files\Alteryx\SslCertificates\server.key
    cert_location: C:\Program Files\Alteryx\SslCertificates\server.crt
...
 

Internal Gateway

The internal gateway provides a way for local and remote Alteryx Workers to communicate with the core services of AAH. Internal gateway settings are also found in Settings.yml, under the internal_gateway.https section: 
 

...
internal_gateway:
  host:
    port: 8080
  https:
    cert_location: C:\Program Files\Alteryx\SslCertificates\server.crt
    ca_key: C:\Program Files\Alteryx\SslCertificates\ca.key
    ca_crt: C:\Program Files\Alteryx\SslCertificates\ca.crt
    ca_password: <redacted>
    ca_bundle: C:\Program Files\Alteryx\SslCertificates\ca.pem
    key_location: C:\Program Files\Alteryx\SslCertificates\server.key
    enable: true
...

Engine Worker

Engine Workers are responsible for managing one or more instances of the Alteryx engine. A single-machine install of AAH includes one engine worker, and you can install engine workers on other remote machines. All workers communicate with the core AAH services via the Internal Gateway.

SSL settings related to the Engine Worker are found in CutlassSettings.yml

...
https:
  enable: true
  encryption_key_path: C:\\Program Files\\Alteryx\\SslCertificates
  certificate_path: C:\\Program Files\\Alteryx\\SslCertificates\\engine-worker.pfx
  certificate_password: <redacted>
  encrypted: true
...

In the examples above, note that Hub’s front-end and internal_gateway share the same SSL certificate and private key (server.crt, server.key). These files are PEM encoded.

The Engine Worker is different. It leverages a PFX archive which includes both the certificate and private key, as well as a password which protects the contents of the archive. 

CAs will not provide you with a PFX archive as doing so would expose your private key to them. Instead, you must generate the PFX yourself using any number of utilities and approaches available to do so. Examples include:

• Openssl tools
• Exporting a PFX from Windows Certificate Store

Creating PFX files is beyond the scope of this article and not supported by Alteryx. 

Configuring SSL with CA-Issued Digital Certificates

To re-configure TLS (SSL) on your AAH deployment, you will use a Windows PowerShell script named ayxhub.ps1. Before following the steps below, make sure: 

• You generated a PFX file as described above.
• You copy your certificate, private key, and PFX file to the AAH machine running core services.
• That you are keeping the files in a well-known, but protected folder. For example, c:\ssl. Do not share this folder widely, and use Windows permissions to limit who can browse its contents.

NOTE: If your CA provided you with intermediate certificates, they should be appended to your host’s certificate. Creating a chain of trust is outside the scope of this article and not supported by Alteryx. Please see this link for details on how to do so.

To Install and Configure CA-Issued Digital Certificates

1. Launch Windows PowerShell in Administrator mode.
2. Navigate to the root folder of your AAH install, for example: cd 'C:\Program Files\Alteryx\Alteryx Analytics Hub'
3. Execute ayxhub.ps1 -https enable, passing in:
   • The path to your certificate
   • The path to your private key
   • The path to the bundle file
   • The path to your PFX archive
   • The password to your PFX archive
     
     Example:ayxhub.ps1 -https enable C:\ssl\host.domain.com.crt C:\ssl\host.domain.com.key C:\ssl\bundle.crt C:\ssl\host.domain.com.pfx password
4. To apply changes, execute ayxhub.ps1 -restart

At any time before you execute ayxhub.ps1 -restart, you can view pending changes in the settings.log file generated in \Alteryx Analytics Hub. If you wish to throw away these changes rather than deploy them, execute ayxhub.ps1 -pending remove

Once complete, examine your Settings.yml file. It will look like this: 

  host:
    port: 443
  https:
    enable: true
    key_location: C:\ssl\host.domain.com.key
    cert_location: C:\ssl\host.domain.com.crt
...
internal_gateway:
  host:
    port: 8080
  https:
    enable: true
    cert_location: C:\ssl\host.domain.com.crt
    key_location: C:\ssl\host.domain.com.key
    ca_bundle: ""
    ca_password: ""
    ca_crt: ""
    ca_key: ""

CutlassSettings.yml should look like this:

https:
  enable: true
  encryption_key_path: C:\\ssl\\host.domain.com.pfx_encryption_key
  certificate_path: C:\\ssl\\host.domain.com.pfx
  certificate_password: <redacted>
  encrypted: true

It is necessary to confirm that each and every engine worker connecting to your AAH platform uses the correct AAH hostname to do so. Follow the steps below for each engine worker, regardless of whether your engine worker is installed on the same machine as core services, or on a different machine. 

Check and Update Engine Worker Configuration

1. Open CutlassSettings.yml in a text editor. 
2. Examine the ayxserver.hostname property. It should not contain localhost. 
3. As necessary, update the hostname property to point to the fully qualified domain name (FQDN) of the computer running AAH core services:

   ayxserver:
     internal_gateway_port: 8080
     protocol: https
     hostname: host.domain.com <-- This is good.

4. Update the host.hostname property to match the ayxserver.hostname. It should not contain localhost.

   host:
     port: 5000
     hostname: host.domain.com <-- This is good.

5. Save your changes. 
6. If you modified CutlassSettings.yml, you must restart the Alteryx Engine Worker service. Execute ayxhub.ps1 -restart.  On a dedicated remote Engine Worker machine, execute ayxworker.ps1 -restart