Enable SSL in Go2Group SOAP Server To enable SSL in Go2Group SOAP service, there are 7 major points you have to follow: I. Install JDK 1.5 or above. (Step 1) II. Use keytool utility to generate RSA key pair in a Java keystore file. (Step 3, 4) III. Use keytool utility to generate CSR (Certificate Signing Request) to apply certificate from CA (Certificate Authority). (Step 5) IV. Import root certificate(s) as trusted certificate(s) into keystore file that generated in 2 nd step. (Step 6, 7, 8) V. Import your SSL certificate into keystore file that generated in 2 nd step. (Step 9) VI. Change server.xml to add required parameters to enable SSL. (Step 10) VII. Test your SSL configuration. (Step 11) We use an example to describe more details about the above 7 points. 1. Make sure you have Java keytool utility in your SOAP server. If the screen shows you the keytool usage, it means the keytool utility exists in your server. If not, please make sure you installed JDK/JRE (1.5 or above) in your server. 2. Stop the Go2Group SOAP server service. 1
3. Before you start to generate key pairs, we DO NOT recommend you generate self-signed certificate, you can apply test certificate from some popular CA such as Verisign or Thawte. If you want to use self-signed certificate, please contact with our support team. 4. Create a keystore and also generate a RSA key pair for SSL in the %Go2GroupSOAPServer_ROOT%/server/default/conf directory. Typing commands in your command mode as the below picture. In this command the server.keystore can be any file name that you want. When you answer the first question: What is your first and last name?, the answer must matches the your domain like: www.your-company.com. If the command execute done, in %Go2GroupSOAPServer_ROOT%/server/default/conf you can find a file named in server.keystore. 2
5. For development environment, we strongly suggest you apply some test SSL certificate from CA such as Verisign or Thawte. For production, we suggest you should purchase a real commercial certificate to configure your server. Now, you have to generate a Certificate Signing Request file (csr file). You still use the keytool utility as the below picture: And then follow your CA s instructions to apply a certificate by using this CSR file. 6. Usually a certificate has a certificate chain that includes its CA s root certificate. You can open your SSL certificate and find it as the below picture. All CAs will send you two or three certificates include your SSL certificate and also some intermediate CA certificates and one root CA certificate, you have to import all certificates into you server.keystore file. 3
7. Before you start to import CA s certificates, you can use keytool list feature to check your CA s certificates exist in your keystore file, as the below picture. 8. If your CA s certificates already existed, you can skip this step. If your CA s certificates don t exist in your keystore file, please import CA s intermediate certificate chain s certificates as the below picture: 4
9. After you import all intermediate CA certificates and root CA certificate, you have to import your certificate as the below picture: 10. You already finished all steps about certificate. Now, you have to change configurations to enable the SSL. Please open the server.xml and edit it. This file locates in %Go2GroupSOAPServer_ROOT%/server/default/deploy/jbossweb -tomcat55.sar directory. And uncomment the SSL/TLS configuration section as the below picture. You can change any port number that you want to open, and make sure the keystorefile attribute point to your keystore file that create in step 3. And also you have to change the keystorepass attribute to your keystore password. 11. Start the Go2Group SOAP server service and open your browser type: https://yourserver:8443/mercuryinterface/mercuryinterface?wsdl, if you can see the same screen as the below picture, it means the SSL enables well in Go2Group SOAP server. 5
6
Configuration in JIRA After you configured the SOAP service server, you have 2 major points to set your JIRA server to accept certificates from your SOAP service server. I. Import your root CA certificate and/or intermediate CA certificate into cacerts file. (Step 1 ~ 5) II. Add two more parameters into your catalina.bat/catalina.sh to use cacerts as trusted CA certificates keystore file. (Step 6, 7) We use an example to describe more details about the above 2 points. 1. We have to import root CA certificate and/or intermediate CA certificates those from the SOAP service server s SSL certificate into cacerts file. The cacerts file locates in your JIRA server s %JRE_HOME%\ lib\security folder. 2. Stop your JIRA server. 3. How can we to get those certificates for importing? If you don t have those certificates, you can open your browser and connect to your SOAP service in https protocol. For example, we use IE 6 to connect SOAP service, in the bottom right of our browser, there is a yellow lock picture, you can double click on it, and it will popup a dialog as the bellowing picture, and then you can save root CA certificates from it. 7
4. Before you start to import CA s certificates, you can use keytool list feature to check your CA s certificates exist in your keystore file, as the below picture. 5. If your CA s certificates already existed, you can skip this step. If your CA s certificates don t exist in your keystore file, please import CA s intermediate certificate chain s certificates as the below picture: 6. We have to add two parameters in catalina.bat or catalina.sh to let JIRA can accept the SOAP service certificate. For Windows, [lease open the catalina.bat file, and append -Djavax.net.ssl.trustStore="%JAVA_HOME%\jre\lib\security\cacerts" -Djavax.net.ssl.trustStorePassword="changeit" at the end of JAVA_OPTS configuration, as the bellowing picture. 8
For Linux, please add two lines configurations in your catalina.sh file as the bellowing. JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$JAVA_HOME\jre\lib\security\cacerts " JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=changeit" 7. Restart your JIRA server and ready to start the JaM Configuration! 9