Overview

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:

  1. Log in to Contrast
  2. Navigate to the user menu in the upper right
  3. Select SuperAdmin in the "Use Contrast Security as:" section
  4. Once in the SuperAdmin view, select System Settings from that same menu

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.

General Settings

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

Licensing

Get a glimpse into license allocation, see if any licenses are nearing expiration, and update your license when needed.

Policy

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.

Security

Manage password policies, two-step verification, and API and application key management. Any change to this setting will require a system restart.

Authentication

Contrast supports a variety of authentications providers:

Any change to this setting will require a system restart.

Database

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.

Mail

Contrast can send email notifications to users when significant events occur (e.g. resetting passwords). You can configure a SMTP server as follows:

Setting Possible Values
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

Log Level

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.

Score Settings

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.

System Messages

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

API Key Management

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.

How it Works

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.

Manage Keys

Enable and change an API key

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 up policies

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.

Password Policy

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.

Manage your Policy

In the Password Policy form, set minimum and maximum requirements for all passwords.

  • Use the dropdown menu to select a minimum Password Strength of Weak, Medium, Strong, Complex or Custom. If you choose Custom strength, enter the number of Minimum Upper Case Letters, Lower Case Letters, Numbers and Symbols in the additional fields that appear.
  • Enter the number of characters required in the Minimum Length field.
  • Use the dropdown menu to choose the length of time allowed before Password Expiration.
  • Enter the number of login attempts allowed before Login Lockout.
  • Choose the length of time allowed before Inactive Account Expiration.
  • Check the box to Restrict Password Reuse, and then use the dropdown menu to choose the number of times each password may be reused.
  • Check the box to Restrict Password Reset, and then use the dropdown menu to choose the number of days during which a user can reset their password .
  • Use the dropdown menus to select the amount of time before Idle Timeout and Session Timeout.

Click the button to Save the configuration.

System Messages

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.

Creating A New System Message

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.

Deactivating System Messages

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.

Administrative Stats

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.

Charts And Metrics

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.

Agent Activity

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.

Queue Breakdown

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.

Logged In Users

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.

Stats

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.

SSL Toolbox

Who Should Read This Document

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:

  • Setting up TeamServer UI HTTPS
  • Integrating with LDAP or Active Directory where you see ldaps://
  • Securing communication between agents and TeamServer

Keytool

Create A Keystore And Keypair

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.

Sample Output:

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

Create A CSR For Existing Keystore

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.

Import A Signed, Root, Or Intermediate CA Certificate Into Existing Keystore

When importing root and intermediate certificates, you will need to be aware of a small change to the -alias and -file options.

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 $JAVA_HOME/jre/lib/security/cacerts.

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.

Root Certificate

keytool -import \
        -trustcacerts
        -alias root
        -file my-root-cert.crt
        -keystore contrast.jks

Intermediate

keytool -import \
        -trustcacerts
        -alias intermediate
        -file my-intermediate-cert.crt
        -keystore contrast.jks

Signed

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

Listing Keystore Contents

When debugging your keystore and client connections, it is helpful to match fingerprints between client and server.

keytool -list \
        -keystore contrast.jks

Output:

$ 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

Export Certificate From Your Keystore

keytool -export
        -alias teamserver
        -file teamserver.crt
        -keystore contrast.jks

Delete An Alias From Your Keystore

keytool -delete \
        -alias teamserver \
        -keystore contrast.jks

Rename An Alias In Your Keystore

keytool -changealias \
        -alias teamserver \
        -destalias contrast-teamserver \
        -keystore contrast.jks

Change Your Keystore Password

keytool -storepasswd \
        -keystore contrast.jks

HTTPS Configuration

Background

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.

Reverse Proxy Method

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.

ajp.enabled=true
ajp.port=8009

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 http.enabled and https.enabled options.

After updating the server.properties file, restart the Contrast server service so that the changes to take effect.

Configuring the front-end server

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.

Contrast HTTPS Connector

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.

Generating a self-signed certificate and KeyStore for SSL termination

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.

Importing SSL certificates verified by third party providers

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.

Enabling and Configuring HTTPS in Contrast Server

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 http.enabled and 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.

Agent Configuration

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.

Contrast.NET Agent

The Contrast .NET agent needs additional configuration to connect to a TeamServer using a self-signed certificate.