Configuring Alteryx Server for SSL: Obtaining and Installing Certificates

[KevinP]

Recently, we have had a number of questions regarding SSL certificates, how to install them, and how to configure the Alteryx Server to use them. While the Alteryx Server Installation and Configuration Guide does cover enabling SSL for Alteryx Server, it doesn’t cover obtaining a certificate, or how to install that certificate so it can be used by the server.

There are a number of tools and methods you can use to obtain an SSL certificate to use with the Alteryx Server. In this article we will be focusing on using OpenSSL to create a Certificate Signing Request (CSR) to send to a Certificate Authority (CA), generating a self-signed certificate, installing the certificate, and configuring Alteryx Server to use the certificate.

Note: If you don’t have OpenSSL installed on your server you can download a precompiled Win32 or Win64 binary from https://slproweb.com/products/Win32OpenSSL.html. Please keep in mind that OpenSSL is not developed, or maintained by Alteryx. That we have no affiliation with the OpenSSL project or the provider of this precompiled binary. As such feel free to use whichever implementation of OpenSSL you are comfortable with.

Creating a Certificate Signing Request with OpenSSL:

*For production deployments, Alteryx and MongoDB recommend using valid certificates generated and signed by a certificate authority. Self-signed certificates are only recommended for development or test environments*

To generate a CSR, open an administrator command prompt on your server and navigate to the directory containing your OpenSSL.exe and configuration file. From there run the following command:

openssl.exe req -config openssl.cfg -out ServerName.csr -new -newkey rsa:2048 -nodes -keyout ServerName.key

This will prompt you to answer a number of questions related to your organization and the server. You can use the included screenshot for your reference, but keep in mind the responses should be based on your organization and server information.

This command will create two files in the same directory with a .csr and .key extension. These files will need to be provided to your CA in order to have your certificate created. This can be either an internal CA or a public CA such as; Verisign, GeoTrust, DigiCert, Entrust, StartCom, etc. The CA will provide you with a signed certificate in return as a .crt, .cer, .pem, or .pfx file.

Creating a Self-Signed Certificate with OpenSSL:

You can also use OpenSSL to generate a self-signed certificate. While this isn’t recommended for production environments there may be a number of reasons why you would want to create one. Some possible reasons include dev or lab environments, and testing to confirm functionality before purchasing a certificate from a public CA. Regardless of your reason, you can do so with the following procedure:

• Open an administrator command prompt and navigate to your OpenSSL directory. Once there, run these commands:

openssl.exe req -config openssl.cfg -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout ServerName.key -out ServerName.crt -addext "subjectAltName=DNS:example.com,DNS:example.net"

openssl.exe pkcs12 -export -out ServerName.pfx -inkey ServerName.key -in ServerName.crt

If you are using OpenSSL 3.0.0 or later, and the second command above does not work, use the following for the second command:

openssl pkcs12 -export -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -nomac -inkey ServerName.key -in ServerName.crt -out ServerName.pfx

In a change from older versions, OpenSSL 3.0.0 uses AES256 as a default to encrypt the private key when exporting the .pfx file. This may not be handled properly in some environments.
 

Spoilers

The -addext "subjectAltName" parameter has been added to the command above to avoid the self-signed SSL certificate throwing up an invalid error.
The subjectAltName should match your FQDN.

If your Gallery URL is HTTP://Localhost/gallery, set your subjectAltName to localhost

The first command generates a signed certificate (.crt file) and private key (.key file). The second command creates a combined certificate and key file in a .pfx format from the generated certificate and key. Please keep in mind you will be asked the same or similar questions as you would if you were generating a CSR. Please reference the screenshots below:

Note: As previously stated we do not recommend using self-signed certificates in production environments.

Installing the Certificate:

Click here for our instructions on the Help docs or use the instructions below with the screenshots as a visual aid.

Once we have received the signed certificate from the CA or generated a self-signed certificate we need to install it. To install the certificate we need to open a Microsoft Management Console (MMC) to access the Certificates snap-in by following these steps:

1. Click Start and then click Run.
2. In the command line, type MMC and then click OK.
3. In the Microsoft Management Console (MMC), on the File menu, click Add/Remove Snap-in.
4. In the Add Remove Snap-in dialog box, click Add.
5. In the Add Standalone Snap-in dialog box, select Certificates and then click Add.
6. In the Certificates snap-in dialog box, select the Computer account radio button because the certificate needs to be made available to all users, and then click Next.
7. In the Select Computer dialog box, leave the default Local computer: (the computer this console is running on) selected and then click Finish.
8. In the Add Standalone Snap-in dialog box, click Close.
9. In the Add/Remove Snap-in dialog box, click OK.

Next, we need to actually import the certificate. To do this:

• Expand Certificates > Personal.
• Right-click on certificates under personal.
• Select All Tasks > Import.

This will open the certificate import wizard.

• Click Next.

• Browse to the certificate file provided by your CA, or the pfx file generated in the self-signing instructions.
• Click Next.

If you are using a self-signed certificate, or your CA issued a certificate that includes the private key you will be prompted for the password/phrase. Otherwise, this step will be skipped by the import wizard.

• Enter the password.
• Check the box to mark this key as exportable.
• Click Next.

The next screen will ask you to confirm where you want to place the certificate. This should have the Certificate store set to ‘Personal’ already.

• Set the Certificate store to Personal if needed.
• Click next.
• On the next screen click Finished.

If you are installing a self-signed certificate we need to repeat these steps in order to establish the local server as a trusted authority. To do this install the certificate a second time following the same steps as above. Except for this time we are going to install it to the Trusted Root Certificate Authorities store instead of the Personal store. You can do this by expanding Trusted Root Certificate Authorities, right-clicking on certificates, and choosing All Tasks > Import, or by changing the Certificate store at the end of the import wizard.

Configuring Alteryx Server to Use the Certificate:

At this point, you can follow the detailed instructions from Step 2 of the Configure Server SSL/TLS Help page  to complete the configuration. Alternatively (and for completeness), you can continue with these simplified instructions.

First, you need to collect the certificate thumbprint for the certificate you installed above. You can do this from MMC > Certificates > Personal > Certificates by right-clicking on the installed certificate and choosing open. This will open a certificate dialog for the certificate you installed. From there, select the Details tab and find the Thumbprint field. Copy the value and remove all spaces from it (e.g. ‎74d4ca722e2954cd225f9b4697d2fc7f6747194c).

Next, you need to check if there is any current certificate bind to the HTTP port 443

netsh http show sslcert

If there is and it does not match the thumbprint value for the app, it can be deleted as follows

netsh HTTP delete sslcert ipport=0.0.0.0:443

You can now proceed to bind HTTP port 443 to the certificate.
To do so, open your administrator command prompt again. Then run the following command, making sure to replace the cert hash with the thumbprint value you captured:

netsh http add sslcert ipport=0.0.0.0:443 certhash=‎74d4ca722e2954cd225f9b4697d2fc7f6747194c appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67}

Spoilers

This is the default appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67} for Alteryx

To check that the binding is correct, you can run the following command:

netsh http show sslcert

Note: When renewing an expired or expiring certificate, you will need to delete the current binding (netsh HTTP delete sslcert ipport=0.0.0.0:443), capture the thumbprint of the new certificate, and rebind the certificate using the instructions above.

For the final step, you will need to configure the Gallery service to use SSL. To do this open Alteryx System Settings and click Next until you reach Gallery > General. Once there find the Base Address section and check the box to Enable SSL. Then click Next, Finished, or Done as appropriate to apply the settings change and restart the Alteryx Service.

Note: The URL must also match the name the certificate was issued to. As such, if the certificate was issued to the server's fully qualified domain name (e.g. hostname.domain.TLD), your URL needs to match this by using https://hostname.domain.tld/gallery/. If the certificate was issued to just the hostname, you would need to use https://hostname/gallery/. If the URL doesn’t match the certificate the service will fail to start properly. This applies for the Base Address, Web API Address, Canonical Base Address, and Canonical Web API Address, where available and applicable.

Additional Resources

• Configure Server SSL/TLS

[KevinP]

Additional Note: If you create a CSR and the CA doesn't return a file that contains the combined key and certificate then you will need to create a .pfx file that contains both the certificate and the key. You can do this in the same manner as directed under the self-signed certificate section. Just use the key created when you create the CSR, and the certificate file received back from your CA with the following command:

openssl.exe pkcs12 -export -out ServerName.pfx -inkey ServerName.key -in ServerName.crt

Once you have a valid .pfx file with the CA signed certificate and key you can import it and bind it to the HTTP service using the information above.

Also, if you install the certificate and it doesn't have an associated key you will get the following error when trying to bind the certificate to the HTTP service port:

The error message is SSL Certificate add failed, Error: 1312

[DurgaS]

Great article @KevinP! Thank you for the detailed instructions!!

[Michal]

Great post, thanks a lot. One additional comment: if you are running server on multiple nodes, make sure you have the same certificate installed on all of them.

[VojtechT]

Hi,

I've just tried this guide and have a minor update for it.

My problem was that Gallery was up and running on https, while the service was starting, but the service didn't manage to finish the starting and stopped. What might be the reason is that there is the "Certificate not trusted" warning somewhere in the background, which you can "Accept" in browser, but not during the service start up. 

So according to this article, you need to add another parameter, so before you generate your certificate, edit the openssl.cfg to contain these lines

[SAN]
subjectAltName=DNS:localhost

or any other domain name you want to run at. 

Then there is one new obstacle - for some reason the Properties of such imported certificate looks completely different, so to obtain the fingerprint you need to find it out from the command line

openssl x509 -noout -fingerprint -sha1 -inform pem -in ServerName.crt

(and this time instead of deleting spaces, delete colons).

Even though I expected the browser to stop asking about the certificate, it still asks, but the service starts and keeps running.

[VojtechT]

* this article

[KevinP]

@VojtechT Thanks for bringing up the SAN (Subject Alternative Name) configuration. When I initial wrote this article the SAN field wasn't required by browsers and the certificate would be trusted as long as the signing certificate authority was and the CN (Common Name) matched. Best practice of course is to use a SAN to also define any alternate or alias names, but it wasn't required at the time. It also makes things a bit more complicated when using OpenSSL to generate a CSR or Cert. Modern browsers all now require that the SAN be present even if you aren't using an alternative or alias name in order to trust the certificate.

As for Designer and Server we still don't hard require the SAN field, but we do require the cert to be trusted (i.e. the URL must match the CN or a SAN if available, and the signing CA must be trusted) for a connection to be established. If the certificate isn't trusted the connection will fail. This includes the service's internal connection to Gallery on startup, and as such can cause the service to fail to start properly. I do plan to update/replace this article with a more comprehensive and updated version as soon as I have some time. Maybe I will even get a chance to cover elliptical curve keys as well as RSA, and generating CSR's and certificate with different tools.

[VojtechT]

Hi @KevinP ,

yes, I might have been to rush to jump to conclusion. My certification wasn't signed, thus not trusted and I was under impression that the presence of SAN was the solution, but apparently there are two:

• either have SAN in the certificate
• or have it trusted AND match the names.

[AnilD]

Hello @KevinP 

This document is of great help. Thank you.

I followed the document and was able to configure SSL but when I try to start the Alteryx Service after make the changes in Gallery, the service does not start or it would start but shuts down in few seconds.

I unchecked the SSL option in gallery and it works again. Any thoughts?

[kbs2018]

How do I find appid? Do I use the appid listed below or there is a command to get appid? netsh http add sslcert ipport=0.0.0.0:443 certhash=‎74d4ca722e2954cd225f9b4697d2fc7f6747194c appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67}

[AnilD]

@kbs2018 Use the appid listed in the document. Its a generic Alteryx ID.

[kbs2018]

@AnilD Thanks Anil for the response. I executed the command and its giving me error "Parameter is incorrect"

[kbs2018]

You can guide me to a video or lin. I checked https://www.youtube.com/watch?v=Nk6HIV-rDL8 but it shows how to get appid for windows. Another link https://4sysops.com/archives/find-the-product-guid-of-installed-software-with-powershell/  shows to go to uninstall but can not see Alteryx there, Also tried to look in 

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID    <Executable_name>       AppID = {AppID_GUID} 

Does it need to be Alteryx appID or Windows APP ID?

[kbs2018]

It worked. For some reason "?" was getting added at the beginning of hash key while copy pasting the command from notepad to command prompt. It worked after removing "?"

[VojtechT]

@AnilD , do you still have that issue with Alteryx Server service not being able to start up? You might check my first comment in this article since I had a similar issue and I am describing there what helped me to solve the problem.

[AnilD]

@kbs2018  Yes, I experienced the same issue. I am glad you were able to resolve.

@VojtechT The issue I had was with the SAN's in the certificate. I was able to resolve it. Thank you.

[paul_houghton]

Hi @KevinP ,

Are there any special considerations for installing on a multi node instance? e.g. does the ssl certificate need to be installed on a particular node?

[KevinP]

@paul_houghton The SSL certificate only applies to the Gallery web ui. As such in a multi-node environment it only needs to be installed on the server or servers running Gallery. If you have more than one gallery node you should ensure each nodes fqdn and any necessary aliases are included in the certificate as subject alternative names (SAN). For example if you have two gallery nodes as server1.domain.tld and server2.domain.tld and users will be access them as gallery-us.domain.tld and gallery-uk.domain.tld the certificate's SAN values should include all 4 names (e.g. server1.domain.tld, server2.domain.tld, gallery-us.domain.tld, and gallery-uk.domain.tld).

[jforte]

Hello everyone, 

SAML Configuration

I installed the certificate with success but when I try to bind it, I get:

C:\Windows\system32>netsh http add sslcert ipport=0.0.0.0:443 certhash=6065c875ac38f3704ffca3827eae43a615010b51 appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67}

SSL Certificate add failed, Error: 1312
A specified logon session does not exist. It may already have been terminated.

And I just can't seem to be able to go through this... has anyone been faced with this ? Googling didn't really help me much 😞

[KevinP]

@jforte please see the very first comment I made on this thread. It provides an additional note about this exact error, what causes it, and how to fix it.

[chvizda]

Hi all

In our environment we need a Server-Certificate with minimum 3072 Bit Key Length.

Can I use the Open SSL by changing it to:

openssl.exe req -config openssl.cfg -out ServerName.csr -new -newkey rsa:3072 -nodes -keyout ServerName.key

Does Altery work with it ?

Many thanks

Steffen

[KevinP]

@chvizda The key length for RSA keys shouldn't matter to our server. As such deploying with a 2048, 3072, 4096, or even higher keys should work without issue. I frequently deploy key lengths at 4096 bit lengths as they are considered more secure with an acceptable performance impact.

Please note it is also possible to use elliptical curve keys instead of RSA keys. If you are going to use an ECC key I highly recommend using a 256 or 384 bit curve for the key, and the matching sha256 or sha384 algorithm for the signature hash. This is because Chrome does not currently support secp521 curves, or sha512 combined with ECC keys. If you would prefer an ECC key The following commands can be used to generate an ECC key and associated CSR that would work with the Alteryx Server and is supported by all major browsers.

openssl ecparam -out ServerName.key -name secp384r1 -genkey

openssl req -config openssl.cfg -new -nodes -sha384 -key ServerName.key -out ServerName.csr

[veronicasimoes]

Great @KevinP 

[yuriy]

@KevinP, I think it would be useful to add a comment regarding the appid within the article so that the users are aware of it right away instead of reading through the comments. And thank you @AnilD for the comment on that.

[Esko]

I'm having an issue were when I go to the netsh-console and paste the line:

netsh http add sslcert ipport=0.0.0.0:443 certhash=‎74d4ca722e2954cd225f9b4697d2fc7f6747194c appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67}

 When I substitute the certhash with the certificates thumbprint I get the following error message: "netsh the following command was not found". Am I doing something obviously wrong?

[Esko]

Managed to get the line working after all!

[LisaL]

@Esko  (and anyone else having this problem)

Sometimes there is a non-display character between the equals sign and the condensed thumbprint.  If you go in and explicitly backspace from the first character of the thumbprint through the equals sign and then type the equals sign and the first character back in, it may work better.

[MBrannelly]

Hi All,

Some great help in here but unfortunately not enough to get me across the line. 

We have a simple installation on a 2019 server. The server also hosts another app which is consuming port 443. 

We have followed the steps in this doc to add a certificate from ZeroSSL and it has installed just fine. 

We have modified the runtime settings file to change our port to port 82

We have modified the gallery url setting in the alteryx settings program. to read //alteryx.ourdomain.com:82/gallery

Our service will not start.

log file states "Gallery Service failed to start in a timely fashion, exiting."

I noticed that while the serive is starting it does establish a listener on port 82. When i try to hit it from my browser as its starting i get "

This might be because the site uses outdated or unsafe TLS security settings. If this keeps happening, try contacting the website’s owner."

So not sure if it is a dodgy certificate issue or what. Pulling my hair out here.

Any help appreciated

[barnese]

Just wanted to save anyone else the headaches I just went through to resolve the "SSL Certificate add failed, Error: 1312
A specified logon session does not exist. It may already have been terminated." error as mine had nothing to do with a private key not being present.  Instead, the system itself did not have access to the file corresponding to the container in the Machine Keys folder.  In CMD run the following command:

certutil -v -store my [insert the thumbrint] 

In the output find the value next to  "Unique container name"

Go to the C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys folder

look for the container name from the certutil output, right click it and select "properties"

Check the "Security" tab and make sure/add "SYSTEM" to the Group or username field (edit button, add button, apply) then click "Apply"

I hope this helps someone!!

[AshBill]

To add to the resolutions regarding the 1312 error, this worked for me:
1. From Command Prompt with Admin privileges run:
certutil -importPFX <certname>.pfx

2. After the above command, try running the command below and check to see if you're now able to see your certificate:
certutil -store my

3. Re-run the command to bind HTTP port 443 to the certificate:
netsh http add sslcert ipport=0.0.0.0:443 certhash=<Thumbprint> appid={eea9431a-a3d4-4c9b-9f9a-b83916c11c67}