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. Additionally, you may enable the redirection from HTTP to HTTPS and enable the HTTP Strict Transport Security (HSTS) policy mechanism.
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 generate a keystore file, use the Java keytool utility. You can find the keytool utility in the $JAVA_HOME/bin directory.
Running the keytool with the following arguments will create a new private key, install a self-signed certificate and generate a new collab.ks keystore file at <Collaborator Server>/tomcat/conf/ directory:
| Tip: | We recommend keeping the keystore file along with Tomcat configuration (for example at <Collaborator Server>/tomcat/conf/collab.ks), yet that is not strictly necessary. You can specify any other name or location. In further instructions we will use the <collab-keystore-path> placeholder instead of the actual keystore path. |
You will be prompted to specify keystore password and 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:
Re-enter new password: <collab-keystore-password>
What is your first and last name?
[Unknown]: collab.acme.com
Once you complete the rest of the prompts, you have created a private key and a self-signed certificate.
 |
Make sure to remember the keystore location and password you set, as you must include them in your server configuration. |
|
Newer versions of Java may use a different keystore format and generate keystores incompatible with older versions of Java. For best results create keystores with the keystore utility from the same version of Java used to run the Collaborator server. |
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:
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 utility. You can find the keytool utility in the $JAVA_HOME/bin directory.
To import the CA chain certificate:
To import the server certificate:
|
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:
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 <Collaborator Server>/tomcat/conf/server.xml file. In the server.xml file, locate the Connector element and replace it with the following:
port="8443" enableLookups="true" disableUploadTimeout="true"
acceptCount="100" maxThreads="100"
scheme="https" secure="true"
SSLEnabled="true" sslEnabledProtocols="+TLSv1.3+TLSv1.2"
keystoreFile="conf/collab.ks" keystorePass="<collab-keystore-password>" clientAuth="false" sslProtocol="TLS"/>
In this XML snippet, you have to replace the keystore password, and keystore path if necessary.
The snippet above, enables the TLSv1.3 protocol. To use the TLS1.3 protocol your Collaborator server should be running on OpenJDK 11 or higher, since support for this protocol was added in OpenJDK 11.
Tip: If you need to specify a full path to the keystore file in server.xml, use the file protocol notation:
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:
Then, print the certificate information that you will need to distribute – especially, the fingerprints. To do this, run the keytool in the following way:
This will print something like the following:
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 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 with 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.
Redirect HTTP requests to HTTPS
To enable the redirection from HTTP to HTTPS, you will need to create both HTTP and HTTPS Connectors in <Collaborator Server>/tomcat/conf/server.xml file and add the appropriate attribute to the web.xml file. For example:
<Connector port="8443" minSpareThreads="5" maxSpareThreads="75" enableLookups="true" disableUploadTimeout="true" acceptCount="100" maxThreads="100" scheme="https" secure="true" SSLEnabled="true" sslEnabledProtocols="+TLSv1.3" keystoreFile="conf/collab.ks" keystorePass="<collab-keystore-password>" clientAuth="false" sslProtocol="TLS"/>
The attribute below should be added after all servlets inside of <webapp> element in the <Collaborator Server>/tomcat/webapps/ROOT/WEB-INF/web.xml file:
<web-resource-collection>
<web-resource-name>HTTPSonly</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>HTTPSorHTTP</web-resource-name>
<url-pattern></url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
This means that the entire application is meant to be HTTPS only, and the container should intercept HTTP requests for it and redirect them to the equivalent "https://" URL. The exception is certain requests having the URL patterns that match the “HTTPSorHTTP” web resource collection. This will allow your end users to use both HTTP or HTTPS for the specified URL patterns.
|
Enable HTTP Strict Transport Security (HSTS)
To enable the HTTP Strict Transport Security (HSTS) policy mechanism, you will need to append the appropriate attribute to the <Collaborator Server>/tomcat/webapps/ROOT/WEB-INF/web.xml file.
In web.xml file locate the following filter element:
<filter-name>Automatic Resource Management</filter-name>
<filter-class>com.smartbear.ccollab.CollabCleanupFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Automatic Resource Management</filter-name>
<url-pattern>*</url-pattern>
</filter-mapping>
and replace it with the following:
<filter-name>Automatic Resource Management</filter-name>
<filter-class>com.smartbear.ccollab.CollabCleanupFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Automatic Resource Management</filter-name>
<url-pattern>*</url-pattern>
</filter-mapping>
<filter>
<filter-name>httpHeaderSecurity</filter-name>
<filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
<async-supported>true</async-supported>
<init-param>
<param-name>hstsEnabled</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>hstsMaxAgeSeconds</param-name>
<param-value>31536000</param-value>
</init-param>
<init-param>
<param-name>hstsIncludeSubDomains</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>antiClickJackingEnabled</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>antiClickJackingOption</param-name>
<param-value>SAMEORIGIN</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>httpHeaderSecurity</filter-name>
<url-pattern>/*</url-pattern>
<url-pattern>*</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
Restart your Collaborator server after the changes have been made.
Additional Resources
See Also
Security Considerations
LDAP and Active Directory Authentication
Admin Tasks