Enterprise On-Premises (EOP) customers can manage their own instance of Contrast. To modify the TeamServer configurations around the system, you must have the SuperAdmin role. Individual users can be granted SuperAdmin on a case-by-case basis. Many of these settings are accessible and can be changed within a specific organization via Organization Settings by an organization administrator as well.
To get to System Settings:
Take a quick peek at the configuration options you'll find inside the System Settings. These settings allow a SuperAdmin to manage security policy, database settings, authentication and more.
The general settings defines the Contrast TeamServer URL for both browsing and RESTful requests. In addition, if an administrator would like to integrate with Contrast Hub for updates of libraries and CVE's, the option to "Try Hub" can be selected. Any change to this value will require you to Restart Contrast.
In the event you moved the installation or had to change the hostname or IP address, here is the place to make that change. Simply update the TeamServer URL field with the new value. Again, any change will require a system restart.
Note: You will have to replace your agents so they know which new address to report to
Get a glimpse into license allocation, see if any licenses are nearing expiration, and update your license when needed.
Manage the library compliance policy for your organization(s). Setup restrictions or version requirements for library usage which will flag violations that break compliance settings.
Contrast supports a variety of authentications providers:
Any change to this setting will require a system restart.
Change this setting with caution. It is very unlikely that a SuperAdmin should need change these values. In the event of system restore operation, the values of this configuration such as URL (contains host information), as well as username and password may require a change. Any change to this value will require a system restart.
Contrast can send email notifications to users when significant events occur (e.g. resetting passwords). You can configure a SMTP server as follows:
|Enable Mail||Enabled or Disabled|
|Mail Protocol||SMTP or SMTPs|
|Mail Host||Fully qualified address of the SMTP server.|
|Mail Port||Likely 25|
|Mail User||User account for authentication purposes on the SMTP system.|
|Mail From||Resetting passwords and alerts|
|Mail Password||Password for mail user associated with the SMTP system.|
|Use SMTP Auth||Checked or Unchecked|
|Enable STARTTLS||Checked on Unchecked|
The SuperAdmin can change the default log level for the various TeamServer log files. Any change to this setting will take place after a system restart.
The score settings for both overall application score and libraries can be customized. This setting allows EOP administrators to configure how scores get calculated, as well as determine if an individual organization can override the setting. For more information, see Score Settings.
SuperAdmins have the ability to send a system message to all users upon immediate login. A simple message and expiration date are required inputs. All users will receive this message every time they login to Contrast until the message expires or is deleted.
For more on configuring system messages, see System Messages
When you download the Contrast JVM plugin (also called the Engine), it comes pre-fitted with a set of randomly generated credentials for your user that don't involve your password. When the plugin communicates with the Contrast site, it authenticates using these credentials.
Contrast added another layer of security through an organization API key that you can enable and manage on your own. In the case of a security breach, an unauthorized user can't submit forged or malicious data to your organization because their organization API key is wrong. With the API key enabled, authentication follows the process shown in the image below.
Go to the User menu > Settings > API tab for details on your current API key. You can also enable your key or update it to a new value.
Set policies for Organization API and application keys as a System Administrator by going to the User Menu > System Settings > Security > Key Management section.
In the Organization API Key section, use the number control fields to enter the number of characters required as well as the minimum number of numerals, upper case characters and lower case characters required in the key. Repeat these steps in the Application Key section. Check the box at the top of the form if you want to Mask invalid IPs on login.
Click the button to Save your selections.
Regulate passwords within your organization by creating a password policy. You must be a SuperAdmin to configure the default policy in the Security tab in System Settings or an Organization Admin to manage the policy in the Security tab in Organization Settings.
In the Password Policy form, set minimum and maximum requirements for all passwords.
Click the button to Save the configuration.
As Contrast becomes an integral part of your development lifecycle, it may become necessary to let users know when things like scheduled downtime will occur, or to let them know that an update has been applied and therefore agents should be updated to the latest version. System Messages provide this functionality to administrators.
To create a new System Message, navigate to System Settings from the User menu at the top right and then select the System Messages tab on the bottom left.
The Create a Message button will generate a dialog allowing you to configure a system message to be broadcast to all users (either after login, or immediately if they are already logged in). This message will display until it is either deleted or reaches its expiration.
When a system message has been set, a user must acknowledge it before they can continue.
Occasionally, you may expect something to take hours and instead it takes only a few minutes. In those cases you may wish to deactivate an active system message. To do so, simply check the box next to the message to select it and click the Delete button.
In addition to overall visibility into TeamServer, there are some specific tools designed to aid administrators in understanding scaling and performance issues, as well as to help troubleshoot user problems and get the most out of Enterprise Deployment.
Administrators have access to a Stats tab in the top navigation menu, which includes various charts and tables displaying valuable information about what is going on with the TeamServer application. At the top of the page, you can choose the refresh rate of these charts and tables.
The Agent Activity chart displays how much traffic is coming in to the TeamServer from Contrast Agents. This includes various types of traffic an agent may send such as App Updates, Traces, and Coverage information.
Administrators can use this chart to identify peak times, average traffic metrics and make determinations about scaling their TeamServer deployment.
The Queue Breakdown chart provides insight into how effectively the TeamServer is handling the aforementioned agent traffic. If queues seem to be growing out of control faster than the TeamServer can handle them, it is a good indication that scaling up or out is necessary.
This view gives you the option to clear the queues if you believe a problem has occurred and that clearing could resolve it (or if instructed to do so by a Contrast Support Agent). While extremely uncommon, it is possible that if corrupted data makes it into one of the Contrast queues, it could freeze the queue and stop processing.
This chart displays all users who are currently logged in to either the User or Administrator interface. Clicking on the Show Details icon on the right will display a modal with additional information about the session.
The stats component shows various bits of information about the JVM and the system that TeamServer is running on. It is broken down into Server, Memory and Memory Pool stats.
This is an overview of useful commands and introductory principles for a person assuming system administration of Contrast TeamServer EOP, where SSL is part of your deployment. The examples presented below are not intended to provide step-by-step instruction, but rather to assist in describing workflows where SSL could be used, as well as the commands possible for implementation and debugging.
At Contrast, we typically see three workflows where SSL is added:
The command below will create a new keystore (if one does not exist), new keypair, and an alias called "teamserver".
keytool -genkeypair \ -alias teamserver \ -keyalg RSA \ -keystore contrast.jks
When running this command, you will be prompted for information to identify yourself and your organization. This command requires a password that you will need to remember for future integrations.
Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: john smith What is the name of your organizational unit? [Unknown]: devteam What is the name of your organization? [Unknown]: Example, Inc What is the name of your City or Locality? [Unknown]: New York City What is the name of your State or Province? [Unknown]: NY What is the two-letter country code for this unit? [Unknown]: US Is CN=john smith, OU=devteam, O=Example, Inc, L=New York City, ST=NY, C=US correct? [no]: y
Taking a look at the directory after this command would show:
$ ls contrast.jks
A certificate signing request (CSR) is what your Certificate Authority needs from you in order to create a SSL Certificate.
keytool -certreq \ -alias teamserver \ -file teamserver.csr \ -keystore contrast.jks
Taking a look at the directory after this command would show:
$ ls contrast.jks teamserver.csr
The teamserver.csr can now be shared with your Certificate Authority. In response, they should send you a signed SSL certificate for use in your environment.
When importing root and intermediate certificates, you will need to be aware of a small change to the
As a general rule, most purchased SSL certificates will be recognized as valid because their Root Certificate Authority is already part of the default keystore. Keep in mind, this will change with your distribution and Java version. The default keystore can be found at
To view the contents of this keystore:
$ keytool -keystore cacerts -list Enter keystore password:
If you are using an internal CA, then you will need to obtain root and intermediate certificates to verify the chain of trust through the keystores on both sides of the connection.
keytool -import \ -trustcacerts -alias root -file my-root-cert.crt -keystore contrast.jks
keytool -import \ -trustcacerts -alias intermediate -file my-intermediate-cert.crt -keystore contrast.jks
Notice here that the alias used is the same in all examples above, specifically the Certificate Signing Request example. The my-ca-signed-cert.crt is what you should receive in response to a CSR.
It is very important that this Signed Certificate is imported to the alias that matches the private key used to create the CSR.
keytool -import \ -trustcacerts -alias teamserver -file my-ca-signed-cert.crt -keystore contrast.jks
When debugging your keystore and client connections, it is helpful to match fingerprints between client and server.
keytool -list \ -keystore contrast.jks
$ keytool -list \ > -keystore contrast.jks Enter keystore password: Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry teamserver, May 6, 2016, PrivateKeyEntry, Certificate fingerprint (SHA1): 5C:23:48:BF:80:2D:AE:78:57:8C:BE:45:C4:39:BA:A8:D8:77:70:D8
To list them verbosely:
keytool -list \ -v \ -keystore contrast.jks
keytool -export -alias teamserver -file teamserver.crt -keystore contrast.jks
keytool -delete \ -alias teamserver \ -keystore contrast.jks
keytool -changealias \ -alias teamserver \ -destalias contrast-teamserver \ -keystore contrast.jks
keytool -storepasswd \ -keystore contrast.jks
By default, Contrast uses HTTP for UI and agent connections. This may not be a big deal in some organizations; in others, you may find that you need to add or replace HTTP with HTTPS for both UI and agent traffic. There are two ways to accomplish this requirement.
Reverse proxy method: Use a standard web server, such as Apache HTTPD or NGINX, in front of the Contrast server configured to reverse proxy requests using Contrast's AJP connector.
Contrast HTTPS connector: Configure Contrast to listen to HTTPS connections on a port that you specify.
Each method has its own benefits. Providing the option to use either method allows Contrast to fit in with many different organization security policies and architectures.
To use AJP with a reverse proxy, you must ensure that the Contrast server is configured to listen for connections using the AJP protocol. To verify this setting, open the $CONTRAST_HOME/data/conf/server.properties file in your text editor and ensure that the following options are set.
You can configure the
ajp.port setting to reflect the port on which you'd like the server to listen for incoming connections. In some cases, you might want to also disable the
After updating the server.properties file, restart the Contrast server service so that the changes to take effect.
Refer to your server's documentation for instructions on how to configure it to use AJP. Also refer to the following links for Apache and NGINX instructions.
Configuring Contrast to use a HTTPS connector is a straight-forward process. These intructions are written in the context that you have a certificate to use. The certificate can be CA signed or self signed.
To begin, import your certificate into a new Java KeyStore (JKS) for use by Contrast. If you already have a KeyStore, you can skip this step and place your KeyStore in the $CONTRAST_HOME/data/conf/ssl directory.
Note: All commands used in this guide should be run in a command shell with administrative privileges from the directory in which Contrast was installed.
This is the quickest and easiest method for generating the proper certificate and KeyStore. The following command prompts you for information about your organization and then generates a KeyStore with a self-signed certificate.
$ jre/bin/keytool -genkey -keyalg RSA -alias contrast-server -keystore data/conf/ssl/contrast-server.jks -validity 365 -keysize 2048
Contrast recommends using this method over generating certificates with OpenSSL. For more complicated SSL configurations, we recommend using a reverse proxy. The following section walks you through enabling SSL in the Contrast server.
To begin, generate a new KeyStore.
$ jre/bin/keytool -genkey -alias contrast-server -keystore data/conf/ssl/contrast-server.jks
Once it's created, import your server's certificate into the new KeyStore.
$ jre/bin/keytool -import -keystore data/conf/ssl/contrast-server.jks -storepass <keystore password> \ -file <path to certificate> -alias <server hostname>
Additionally, you may need to import intermediate CA certifications into the KeyStore. (See your CA's documentation to verify that this is the case.) For a private CA server, you need any intermediate certificates and the root CA certificate in the KeyStore.
$ jre/bin/keytool -import -trustcacerts -alias <ca-name> -storepass <keystore password> \ -file <path to ca or intermediate certificate>
Note: In order for the Contrast UI to use the SSL Certificate, the certificate can't be protected with a passphrase.
Once KeyStore setup is complete, open the $CONTRAST_HOME/data/conf/server.properties file in your text editor and update the following properties.
https.enabled=true https.port=<port to listen for https connections on> https.keystore.file=<full path to jks created above> https.keystore.pass=<password for the jks created above> https.keystore.alias=<hostname of the server>
You may find it useful to set the
ajp.enabled options to false to ensure that only connections made over HTTPS are allowed to the Contrast server.
After updating the
server.properties, restart the Contrast server service and ensure that it's now listening on the HTTPS port you configured.
If you switch from HTTP to HTTPS, update the server to tell future Contrast agents that they should connect back using HTTPS instead of HTTP.
Open the $CONTRAST_HOME/data/conf/general.properties file and change the value of the teamserver.url property to reflect your change. Agents must be updated manually the first time after you make this change. Future updates to the agent will be automatic.
The Contrast .NET agent needs additional configuration to connect to a TeamServer using a self-signed certificate.