Applies to Collaborator 12.2, last modified on November 21, 2019

The basic Collaborator installation configures the server to handle requests over standard HTTP. In many environments this is sufficient as the network is trusted. However some organizations require that all network applications are secured with Transport Layer Security (TLS) or Secure Sockets Layer (SSL). Collaborator supports HTTP over TLS (or HTTPS), but this requires additional manual server configuration.

What You Need

Certificates

To authenticate to clients, the Collaborator server must have a certificate that serves as proof of identity. Certificates come in two forms: Certificate Authority (CA) signed certificates and self-signed certificates. CA-signed certificates provide an additional level of security because they can be automatically verified and do not rely on human verification. By providing you a certificate, the certificate authority is vouching for your identity. Software systems such as web browsers and the Java Runtime Environment (JRE) include the public keys of the trusted certificate authorities that are used to verify server certificates were vouched for by a trusted CA. To acquire a CA-signed certificate, contact the appropriate person in your IT department.

Self-signed certificates have the advantages of being free and easy to generate. The disadvantage of self-signed certificates is that they cannot be automatically verified. Instead, their security relies on users verifying the certificate signature against a signature obtained through another, ideally secure, channel.

Keystores

A keystore is a mechanism for storing cryptographic keys and certificates in Java. The persistent form of a keystore is a password-protected file on disk. A keystore may contain key entries that allow applications with access to the keystore to authenticate themselves to users or other services. A keystore is also used to store trusted certificate entries that contain the public keys of services that are trusted and certificate authorities that are trusted to vouch for services.

To enable HTTPS in Collaborator, you will need to create a keystore with the certificate of the server (either CA, or self-signed). For CA-signed certificates – the chain certificate the certificate authority. Follow the instructions below to create a keystore with the type of certificate you will be using to secure Collaborator.

Create Collaborator Keystore

Create private key and certificate in your keystore

To get started, you must use the Java keytool command (located in <Java home directory>/bin). Running keytool as follows will create a new private key and install a self-signed certificate:

keytool -genkeypair -alias tomcat -keyalg RSA -validity 360 -keysize 2048 -keystore <Collaborator Server>/tomcat/conf/collab.ks

You will be prompted to answer a series of questions. When you are prompted to enter your first and last name, enter the host and domain name you intend to use to address the Collaborator server instead. For example:

What is your first and last name?
[Unknown]: collab.acme.com

Once you complete the rest of the prompts and assigned a password to the keystore, you have created a private key and a self-signed certificate. Make sure to remember the keystore password you set, as you must include it in your server configuration.

For many organizations, this is sufficient to guarantee security. However, web browsers and the Collaborator client will request confirmation from end users, unless the certificate is not signed by an existing certificate authority.

If you wish to have a certificate authority sign your server certificate, please follow the steps described in Create Certificate Signing Request.

Create certificate-signing request

After the steps described above, you can create a certificate-signing request with the following command:

keytool -certreq -alias tomcat -keystore <Collaborator Server>/tomcat/conf/collab.ks -file tomcat.csr

You will be prompted to enter the keystore password. This should create a file named tomcat.csr which you will need to provide to your signing authority. This may be Verisign, Thawte, another certificate vendor, or a group internal to your organization. Once they have verified the information provided, the signing authority will send you a certificate file.

Import CA-signed certificates

If you are using a CA-signed certificate, you will need the server certificate and the chain certificate of the certificate authority (or root certificate). The CA chain certificates are publicly available, but the instructions for acquiring them vary by certificate authority. To get the CA chain certificate, ask the IT person in your organization responsible for procuring SSL certificates for services. Once you have the certificates, import them into a new keystore using the Java keytool program (located in <Java home directory>/bin).

To import the CA chain certificate:

keytool -importcert -alias root -keystore <Collaborator Server>/tomcat/conf/collab.ks -trustcacerts
-file <path to chain certificate file>

To import the server certificate:

keytool -importcert -alias tomcat -keystore <Collaborator Server>/tomcat/conf/collab.ks -trustcacerts
-file <path to server certificate file>

Remember the keystore password you select, as you will need this when configuring the Collaborator server.

Import server and chain certificate simultaneously

Some popular signature authorities now provide both a primary and intermediate certificate. The steps below may work more effectively in those cases than the steps above.

First, assemble a single file containing all of the certificates (primary, intermediate, and server) provided to you by your signature authority:

  • On UNIX systems – Use the following code line:

    cat primary.cert intermediate.cert tomcat.cert > combined.txt
  • On Windows systems – In Notepad, copy and paste all the provided certificates into a single file, then save it as combined.txt. After that, run the following command:

    keytool -importcert -alias tomcat -keystore <Collaborator Server>/tomcat/conf/collab.ks -trustcacerts -file combined.txt

    This will import all three (or more) certificates at the same time, establishing the correct chain of trust.

Configure Collaborator Server

The final step in configuring the Collaborator server is to instruct the server to use SSL and tell it what certificates to use. This is done by editing the server.xml file located in <Collaborator Server>/tomcat/conf. In server.xml, locate the Connector element and replace it with the following:

<Connector protocol="org.apache.coyote.http11.Http11Protocol"
port="8443" enableLookups="true" disableUploadTimeout="true"
acceptCount="100" maxThreads="100"
scheme="https" secure="true"
SSLEnabled="true" sslEnabledProtocols="TLSv1.2,TLSv1.1,TLSv1"
keystoreFile="conf/collab.ks" keystorePass="<the keystore password>" clientAuth="false" sslProtocol="TLS"/>

In this XML snippet, you have to replace the keystore password.

Tip: If you need to specify a full path to the keystore file in server.xml, use the file protocol notation:

keystoreFile="file:///c:/program%20files/collaborator%20server/tomcat/conf/collab.ks"

Restart the server and it will be operating over SSL on port 8443.

Make sure to update the External URL in the server settings to reflect the correct HTTPS URL and enable the Secure authentication cookies setting to send login cookies over HTTPS.

Impact on Clients

After you have generated the keys for the server, you may wish to distribute a keystore and its signature to users so they can validate the certificate when asked. To do this, first export the certificate to a file:

keytool -exportcert -keystore <Collaborator Server>/tomcat/conf/collab.ks -alias tomcat > <export path>collab.cert

Then, print the certificate information that you will need to distribute – especially, the fingerprints. To do this, run the keytool in the following way:

keytool -printcert -file collab.cert

This will print something like the following:

Owner: CN=collab.aus.smartbear.com, OU=SmartBear, O=SmartBear, L=Austin, ST=TX, C=US
Issuer: CN=collab.aus.smartbear.com, OU=SmartBear, O=SmartBear, L=Austin, ST=TX, C=US
Serial number: 463251eb
Valid from: Fri Apr 27 14:41:31 CDT 2007 until: Thu Jul 26 14:41:31 CDT 2007
Certificate fingerprints:
MD5: 67:D7:74:5E:72:9D:B2:82:88:3F:33:AA:A0:41:01:F0
SHA1: E2:4A:1F:9B:9A:38:0F:6B:7B:33:12:73:1B:50:76:30:AC:A6:B2:EA

If the certificate used to secure Collaborator is a CA-signed certificate from a trusted certificate authority, there will be very little impact on users. The only thing that they must do is configure their clients with the correct HTTPS URL.

If you are using a self-signed certificate or the certificate cannot be automatically verified, users will be asked to verify the certificate by comparing its signature to the published signatures for the service. The exact nature of this confirmation varies by client, but the process is the same: look at the certificate the server presents and confirm that its signature matches the published signature.

In the web browser, the certificate confirmation dialog should look as follows:

The certificate confirmation dialog in Firefox

The above screenshot is from Firefox, but other browser users will see a similar dialog. The users will need verify that the fingerprint (or signature) of the certificate by comparing it to the signature of that you distributed for the server.

Certificates that are accepted permanently are stored in a local keystore in $HOME/.smartbear/trustedcertificates. This file can be deleted safely to remove all trusted certificates. If this is done, the user will have to reauthorize any certificates that are self-signed (or signed by a CA that is not in the Java trusted keystore).

If you want each client to automatically recognize and authorize your internal CA without being prompted to do so, one solution is to accept the key with one client, and then distribute the trustedcertificates file that is generated.

To reiterate, the default location for Unix clients is: ~/.smartbear/trustedcertificates; for Windows clients: %USERPROFILE%\.smartbear\trustedcertificates.

If you can distribute the necessary files to all user machines, distributing that file to those locations will prevent remaining users from seeing the prompt.

Unlike other clients, Collaborator Visual Studio Extension cannot read certificates from Java keystore. Therefore, to work with HTTPS servers from Collaborator Visual Studio Extension, users should manually install the server certificate into the Windows keystore.

Note: For self-signed certificates, you have to use a certificate signed wiht certificate authority. It can be any CA – even yourself. You will also have to install the CA certificate in question in trusted authorities, since you cannot use the self-signed certificate directly.

For more information, see the Configuring HTTPS Connection section of Visual Studio Extension Configuration.

Additional Resources

See Also

Security Considerations
LDAP and Active Directory Authentication
Admin Tasks

Highlight search results