Managing SSL certificate

On this page:

By default, Teamwork Cloud and Web Application Platform use a self-signed certificate generated during installation. However, for production environments, it is strongly recommended that you use a certificate signed by a trusted Certificate Authority (CA). Follow the steps outlined on this page to replace the self-signed certificate with a CA certificate and Java keystore, provided that you either have a private key and certificate signed by a trusted CA, or a PFX file containing the private key and signed certificate.

Changing the self-signed certificate to a CA certificate

If you have PFX file, expand the section below to prepare the files needed.

The new certificate will have to be converted to a Java keystore for Teamwork Cloud components. Use the following procedure to update the keystore file with your new certificate and private key files.

To change the self-signed certificate using the keystore file

1. Locate the default keystore file at <install_root>/configuration/keystore.p12.

2. Update the keystore file with the new private/public key:

   1. Create a PKCS 12 file with the OpenSSL tool:

      openssl pkcs12 -export -name teamworkcloud -in teamworkcloud.crt -inkey server.key -out keystore.p12

      In the example above, teamworkcloud is a sample alias. If you use a different alias, remember to update it in the <install_root>\WebAppPlatform\shared\conf\authserver.properties file.

   2. Copy the keystore.p12 file to the <install_root>/configuration directory, replacing the default file with the new one.

3. Add the public certificate file to the <install_root>/configuration directory.
   

   The public certificate file, or .crt, is the public key from the private/public (.key/.crt) key pair.

4. (Recommended) Secure .key and .p12 files with a password. Make sure to keep the .key file in a safe place.

5. If you need to switch from IP to FQDN, see how to change server or service address.

If the default configuration (file names, locations, passwords, aliases, etc.) is not changed, no additional steps are necessary. However, if you are changing the default configuration, then you also need to update the relevant properties in the corresponding files, as described below.

Updating service configuration

Updating Teamwork Cloud configuration

Update the default values for the properties indicated below in the <install_root>/configuration/application.conf file if any of the applicable values were changed.

https {
        # the file name of the certificate or the key store (should be a full path)
        file = "configuration/teamworkcloud.crt"
}

ssl {
		keystorePath = "configuration/keystore.p12"
		keystoreType = "pkcs12"
		keystorePassword = "nomagic"
		keyPassword = "nomagic"
}

Updating Authentication server configuration

Update the default values for the properties indicated below in the <install_root>/WebAppPlatform/shared/conf/authserver.properties file if any of the applicable values were changed.

authentication.server.key-store=../configuration/keystore.p12
authentication.server.key-store-type=PKCS12
authentication.server.key-store-password=nomagic
authentication.server.key-password=nomagic
authentication.server.key-alias=teamworkcloud

Updating Web Application Platform configuration

Update the default values for the properties indicated below in the <install_root>/WebAppPlatform/conf/server.xml file if any of the applicable values were changed.

<Certificate    certificateKeystoreFile="../configuration/keystore.p12" 
				certificateKeystorePassword="nomagic" 
				type="RSA" 
/>

Both services (Teamwork Cloud and Web Application Platform) must be restarted once all of the configuration changes are completed.

Regenerating self-signed keystore

You may need to regenerate the self-signed keystore and certificate from the initial Teamwork Cloud installation. Restoring the system with the self-signed certificate will help with troubleshooting keystore/certificate issues. 

To regenerate self-signed keystore and certificate for Teamwork Cloud

1. Move or delete the current keystore.p12 and teamworkcloud.crt files located in the configuration directory (default path: <install_root>/TeamworkCloud/configuration).
2. Execute the genkey script associated with the server's operating system, located in the scripts directory (default path: <install_root>/TeamworkCloud/scripts).
3. Confirm the newly-generated keystore.p12 and teamworkcloud.crt files exist in the configuration directory. Ensure there is a read permission and ownership to user "twcloud." The keystore is reset to original parameters (alias: teamworkcloud; password: nomagic)
4. Restore keystore/certificate service configurations specified in the previous section.
5. Restart twcloud and webapp services.

Useful OpenSSL Commands

To check a private key:

openssl rsa -in <private_key_file> -check

To check a signed certificate:

openssl x509 -in <certificate.crt> -text -noout

To check a PKCS#12 file (.pfx or .p12):

openssl pkcs12 -info -in keystore.p12