127 Church Street, New Haven, CT 06510 O: (203) 789-0889 E: sales@square-9.com www.square-9.com
GlobalForms SSL Installation Guide The following guide will give an overview of how to generate and install a SSL (Secure Sockets Layer) certificate into your Tomcat installation, which the GlobalForms application is using as a webserver. There are several important things to note before beginning this process. 1. You must have an external FQDN (Fully Qualified Domain Name) pointed to your GlobalForms server. For example, http://www.square-9.com. Local server names such as localhost or globalformsserver.local will not work. 2. There are many different kinds of SSL certificates, such as EV SSL certificates, Wildcard SSL certificates, etc. This guide will be focused on installing a single standard SSL certificate for a single domain or subdomain. 3. Wildcard or standard SSL certificates generated for IIS will not work with a Tomcat web server. 4. Every Certificate Authority (CA) has slightly different procedures for installing the SSL certificate. This guide was written using an Instant SSL certificate issued by Comodo. 5. In order to verify ownership of your domain, you must have access to the administrative email address listed on the WhoIs information for that domain. If you do not have access to this email account, please contact your network administrator. In addition to the above considerations, you must open port 8443 on your firewall to allow https communication to your server. The following steps assume you have a working production installation of GlobalForms and have access to the GlobalForms server. Step 1 Create your Certificate Signing Request A Certificate Signing Request or CSR is a file that is created on a server that contains encrypted identifying information about the server and organization and is sent to a Certification Authority or CA in order to generate a SSL certificate. An encrypted public key or keystore must be generated first so that the CA can identify the server. Creating a keystore 1. Open an administrator command prompt on the server that is running GlobalForms 2. Browse to the bin directory of your JAVA_HOME with the following command: cd C:\Program Files\Java\jdk1.7.0_02\bin NOTE: Make sure to replace the jdk version number with your correct version number. If you are on a 32 bit machine replace Program Files with Program Files (x86). 3. Create your keystore by using the keytool command. keytool genkey alias tomcat keyalg RSA keystore globalforms.keystore Simplifying Business. Simplifying Life. Page 2
4. Once you issue that command, it will prompt you to create a password for your keystore. This password should be complex. When typing in the password, you will not see any characters being entered into the command prompt window. This is done on purpose for security. 5. Confirm your password and then fill out the prompts for your information. NOTE: For some CAs, you must put your FQDN in the prompt where it says what is your first and last name, ie: globalforms.square-9.com. 6. Once you have finished filling out the information, it will show the information back to you and ask if the information is correct. By default the answer is no and shown in brackets [no]. Type in yes and hit enter. It will then ask you to create a password for the tomcat csr alias you just created. You can just press enter to use the same password for the keystore. 7. Browse to this directory to make sure your keystore file was created successfully. Simplifying Business. Simplifying Life. Page 3
8. Now that our keystore has been created successfully, we can create our CSR that we will be sending to the CA. Issue the following command: keytool certreq keyalg RSA alias tomcat file certreq.csr keystore globalforms.keystore 9. You will then be prompted for a password. Enter the password that you used to secure your keystore so that we can create a new entry with the CSR. Step 2 Submit your CSR to a CA If the previous command to generate the CSR was completed successfully, you should not have a file called certreq.csr in your bin directory along with your original globalforms.keystore. The next step is to take the CSR you created and submit it to a CA. 1. Open the CSR you created in a plain text editor such as Windows Notepad or Notepad++ (do not use a Rich Format Text Editor such as Microsoft Word). Simplifying Business. Simplifying Life. Page 4
2. When you open your CSR, it should appear similar to what is below: -----BEGIN CERTIFICATE REQUEST----- MIIC8jCCAdoCAQAwfTELMAkGA1UEBhMCVVMxFDASBgNVBAgTC0Nvbm5lY3RpY3V0 MRIwEAYDVQQHEwlOZXcgSGF2ZW4xETAPBgNVBAoTCFNxdWFyZSA5MREwDwYDVQQL EwhGcmVlRm9ybTEeMBwGA1UEAxMVZnJlZWZvcm0uc3F1YXJlLTkuY29tMIIBIjAN BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtNfKqxpASKpTOfbOoPIvo71hy2Qu arcy540d4jygnlho+atvgaleb580qkmddfnyechs9/ftbkhyswliw7pwrqaqgtjm izmflkpduugctvjuyrhdwyufhcevsdl6hdfzfkhi6cxmg8rtvd/aegw4gwb8pu96 GpH3LD5qibaUfQWoiT58V7IP3yprXKUl619v+eKtm/uZ37RQwm+S2lRFVMFZvQqt E4jPs/bTZW1MI2TtlyvrR9vJlWBj2lqrMMAbnNWGVSXr6Whv+52vzREAGn0wecOh mwcrh3nczvjlezh8naj0rkwzlxjxxk5+ocg5fjpjzlkzjofbhgxmdheyuqidaqab odawlgyjkozihvcnaqkomsewhzadbgnvhq4efgquw5fpcfrhw0udlgdic48xn8xy KtYwDQYJKoZIhvcNAQELBQADggEBAIYiPNU1BNrtw9ZVq1b8G2xdHFcQzTSF4IdA xjwv0xndje9rlxosxxeylae3kyhxume3kdu0s27aai2s3fngcryhxbqracuw3cmq kq2b3za/p4yu6vg+jyzayywwhuxa/fjchedc0giqosbaqnz4yjfd9plwmyw5bkjr RnWEx8C4xYozYJdkMVQpc5s8E0ayynZxy7ZW9djG72hYmKnP/OrI7SU5dKCGX/xl Aa+tgfWLnIbo49Cm2WfYl3FoKBortxh1xIqGkEAaAaLcxIsyGhIf1IpfpJASoi8E VUR9ED17BRXb/G/vruN5ocJ4gDedPgSCAq3mTQdhR+0wXTB1DIc= -----END CERTIFICATE REQUEST----- 3. Take your CSR code, including the BEGIN CERTIFICATE REQUEST and END CERTIFICATE REQUEST sections, and submit them to your CA. Make sure you select Tomcat as your server type. Simplifying Business. Simplifying Life. Page 5
Step 3 Domain Verification Each SSL provider and CA issuer may have a different process for verifying domain ownership. Most often it is done with email verification to one of the following email addresses: admin@[yourdomain.com] administrator@[yourdomain.com] hostmaster@[yourdomain.com] postmaster@[yourdomain.com] webmaster@[yourdomain.com] Alternatively, you may have the option to send it to the email listed on the WHOIS information for the domain. Please refer back to your CA for domain verification processes. Step 4 Installing the SSL Certificate Depending on your method of verification, you may receive your SSL Certificate files in at little as 5 minutes. Most likely they will come in the form of an email with a zip file containing 2 or more files. In this example, I received the following files in my zip package: AddTrustExternalCARoot.crt ComodoUTNSGCCA.crt EssentialSSLCA_2.crt UTNAddTrustSGCCA.crt globalforms_square-9.com.crt Simplifying Business. Simplifying Life. Page 6
1. Place these files into the bin directory of your Java installation. 2. These files are root and intermediate certificates, which are used to verify that your SSL certificate is valid. We are now going to import the root and intermediate certificates into our keystore. It is very important that you import the certificates in their proper hierarchy. Your CA should have documentation outlining the certificate hierarchy. Simplifying Business. Simplifying Life. Page 7
3. Issue the following command to import the Root certificate. Make sure to replace the certificate name with the one issued by your CA: keytool import trustcacerts alias root file AddTrustExternalCARoot.crt - keystore globalforms.keystore 4. Enter the password you created for your keystore and answer yes if it asks you if you are sure you want to import the certificate. 5. Next, import your intermediate certificate(s) in the proper hierarchy: keytool -import trustcacerts alias INTER file UTNAddTrustSGCCA.crt keystore globalforms.keystore 6. Enter the password you created for your keystore. keytool import trustcacerts alias INTER1 file ComodoUTNSGCCA.crt keystore globalforms.keystore 7. Enter the password you created for your keystore. keytool import trustcacerts alias INTER2 file EssentialISSLCA_2.crt keystore globalforms.keystore 8. Enter the password you created for your keystore. 9. Finally, import your domain SSL Certificate: keytool -import alias tomcat keystore globalforms.keystore file globalforms_square-9_com.crt 10. Enter the password you created for your keystore. 11. Once you have imported the certificates into your keystore, your SSL installation should be complete. Step 5 Configuring GlobalForms to use the SSL Certificate By default GlobalForms comes installed with a self-signed SSL certificate. Now that we have a CA signed SSL certificate we need to reconfigure GlobalForms to point to the new keystore. 1. Browse to: [globalforms directory]\frevvo\tomcat\conf\ Simplifying Business. Simplifying Life. Page 8
2. Open server.xml in a text editor such as Windows Notepad or Notepad++ (do not use a Rich Format Text Editor such as Microsoft Word). 3. Find the following section: <!-- HTTPS Connector : add algorithm="ibmx509" when using IBM's J9 JVM --> <Connector port="8443" protocol="org.apache.coyote.http11.http11nioprotocol" SSLEnabled="true" maxthreads="150" scheme="https" secure="true" clientauth="false" sslprotocol="tls" keystorefile="${catalina.home}/conf/keystore" keystorepass="password" connectiontimeout="20000" maxhttpheadersize="32768" usebodyencodingforuri="true" /> 4. Change the highlighted line to point to your keystore for the section that says keystorefile and change the keystorepass to your keystore password. It should look something like this: 5. After you make these changes, save your server.xml file and restart the ssglobalforms services in your Services Control Manager. Simplifying Business. Simplifying Life. Page 9
6. Once the GlobalForms service has restarted, browse to your GlobalForms URL that you used on the SSL certificate. Please make sure to use the default Tomcat SSL port 8443 rather than 8082. In this example, my URL is: https://globalforms.square-9.com:8443/frevvo/web/login. Notice that we also need to use https instead of http. When you browse to this URL you should not see the secure padlock on your browser. 7. When clicking on the lock you should see your SSL certification information. Simplifying Business. Simplifying Life. Page 10