Overview

Enterprise-on-Premises (EOP) customers can manage their own instance of Contrast, including security policy, database settings and authentication. To modify system configuration settings for the Contrast application, you must have the SuperAdmin role. Individual users can be granted SuperAdmin permission on a case-by-case basis. Organization Admins can also access and change many of these settings for a specific organization in Organization Settings.

Find System Settings

To get started in System Settings, log in to your Contrast application. Go to the user menu in the top right corner (by your profile name and image), and select SuperAdmin. Once you're in the SuperAdmin view, open the user menu again, and select System Settings.

General Settings

General settings define the Contrast application URL for both browsing and RESTful requests. In addition, you want to integrate with Contrast Hub for library and CVE updates, you can select the option to "Try Hub". Any change to this value will require you to Restart Contrast.

If 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 address they should report to.

Licensing

Get a glimpse of license allocation, see if any licenses are nearing expiration, and update your license when needed. For more information, read how to Manage Licenses in Organization Settings.

Policy

Manage the compliance policy for your organization(s) by creating restrictions or version requirements for libraries. Contrast will then flag libraries that violate the compliance settings, and alert you to violation.

Security

Manage password policies, two-step verification, and API and application key management. You must restart the Contrast application after any change to these settings.

Authentication

Contrast supports a the following authentications providers. Any change to this setting requires a system restart.

Database

Change this setting with caution. It's very unlikely that a SuperAdmin will need change these values. In the event of a system restore operation, changes to the values of this configuration - such as the URL, which contains host information, or username and password - may be required. Any change to this value also requires a system restart.

Mail

Contrast can send email notifications to users when significant events occur, like a password reset. Configure settings for a SMTP server using the following fields.

  • Enable Mail: Use the toggle to enable or disable the feature.
  • Mail Protocol: Values can be "SMTP" or "SMTPs".
  • Mail Host: The fully qualified address of the SMTP server.
  • Mail Port: The likely value is "25".
  • Use SMTP Auth: Check the box to enable this setting.
  • Mail User: A user account for authentication purposes on the SMTP system.
  • Mail Password: The password for the mail user associated with the SMTP system.
  • Mail From: Use this setting to reset passwords and alerts.
  • Enable STARTTLSL: Check the box to enable this setting.

Log Level

The SuperAdmin can change the default log level for the various log files. Any change to this setting will take effect after a system restart.

Score Settings

You can customize the score settings for both overall application score and libraries. This setting allows EOP administrators to configure how scores get calculated and permit an individual organization to override the setting.

System Messages

If you want to alert all users in your organizations to important changes, you can send a system message, which they'll receive every time they log in to Contrast until the message expires or is deleted.

Diagnostics

Contrast Diagnostics measures customer usage of Contrast products to help Contrast provide faster, more proactive support and guide delivery of new functionality.

How It Works

Contrast periodically sends snapshots of relevant data elements and data aggregations up to Contrast Diagnostics, a service on Contrast’s Software as a Service (SaaS) platform. Data that could be used to identify a customer or organization is obscured using a one-way hash, and is encrypted both in transit and at rest. Due to privacy concerns, the data doesn’t include application names, personally identifying information, code, vulnerability identities or customer network identifiers.

Data collection

As Contrast securely transmits the data over an encrypted connection to the Contrast Diagnostics service, the data is anonymized and not attributable to any particular Contrast installation. The data is then stored in the Contrast Diagnostics database, where it’s made available to approved Contrast Support and Product Development users for analysis and reporting. Within the database, the data is attributed to customers to provide Customer Support insight into how to better assist Contrast customers.

Why It Works

Diagnostics helps Contrast provide proactive support to customers through technical assistance and expert guidance in three main areas.

  • Customer Support will analyze the data sent back to Contrast for markers, which can indicate potential issues, and allow Customer Support to reach out proactively and work with you to prevent problems.

  • Contrast can use the collected data to quickly diagnose existing problems and reduce the cycle time for successfully resolving support cases.

  • Insight into deployment and usage helps Contrast product development teams to adjust and deliver new functionality to help customers get the most out of their Contrast deployment.

Settings

SuperAdmins can enable and disable the Contrast Diagnostics feature through the SuperAdmin dashboard. SuperAdmins may also use the Contrast REST API to preview the data that will be transmitted to Contrast Diagnostics. You can find information about how to use the REST API in Contrast’s API documentation.

To view the Diagnostics setting in the Contrast UI, go to the user menu > System Settings > General Settings > Internet Settings section. Diagnostics is enabled by default; however, you can use the toggle to disable and re-enable it as needed.

Note: Your proxy settings apply to your Hub and Diagnostics settings.

System Messages

As Contrast becomes an integral part of your development lifecycle, you might want to let users know about situations like scheduled downtime or that an update has been applied. System messages allow you to immediately alert all users in your organizations every time they log in to Contrast, and continue to send the alert until your chosen expiration date.

Create a Message

To create a new system message, navigate to your SuperAdmin view, and go to the user menu > System Settings > System Messages tab.

Click the button to Create a Message. In the dialog that appears, set an expiration date and time for the message, and add the text in the Message field. Contrast will display this message until you deleted or it reaches expiration.

Note: Users must manually acknowledge system messages before they can continue with their tasks in the Contrast UI.

Delete a Message

If you want to immediately deactivate an active system message, use the checkbox to select the message, and click the Delete button.

Administrative Stats

The Stats dashboard is designed to help administrators get the most out of Enterprise-on-Premises (EOP) deployment through better understanding of scaling and performance issues, as well as to help troubleshoot user problems.

Go to the Stats page from the top navigation menu to view data on your Contrast application. At the top of the page, use the button to change the refresh rate of the charts and tables.

Queue Breakdown

The Queue Breakdown chart shows you how effectively the Contrast application is handling the agent traffic. If queues seem to be growing faster than Contrast can handle them, it's a good indication that you should scale up or out.

While extremely uncommon, it's possible that corrupted data could make it into one of the Contrast queues, and cause the queue to freeze and stop processing. If you believe a problem has occurred and that clearing could resolve it, or if instructed to do so by a Contrast Support Agent, click the Clear Queues button.

Logged In Users

The Logged In Users chart displays all users who are currently logged in to either the user or administrator UI. Click on the Show Details icon to see additional information about each user's session.

Stats

The Stats section shows compiled information about the JVM and the system on which Contrast is running. The data is separated into Server, Memory and Memory Pool tables.

SSL Toolbox

If SSL is part of your Enterprise-on-Premises deployment, SystemAdmins may find the following commands and introductory principles to be useful.

There are three workflows in which Contrast users typically add SSL:

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

The following examples are intended to help describe workflows in which SSL could be used, as well as the possible commands for implementation and debugging.

Keytool

Create a KeyStore And KeyPair

The following command will create a new KeyStore (if one doesn't exist), 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 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

The directory after this command would show:

$ ls
contrast.jks

Create a CSR

Your certificate authority (CA) needs a certificate signing request (CSR) from you to create a SSL certificate.

keytool -certreq \
        -alias teamserver \
        -file teamserver.csr \
        -keystore contrast.jks

After this command, the directory would show:

$ ls
contrast.jks    teamserver.csr

You can now share the teamserver.csr with your CA. In response, they should send you a signed SSL certificate to use in your environment.

Import a CA Certificate

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 CA is already part of the default KeyStore. However, the default will change with your distribution and Java version. You can find the default KeyStore at $JAVA_HOME/jre/lib/security/cacerts.

To view the contents of this KeyStore, use:

$ keytool -keystore cacerts -list
Enter keystore password:

If you're using an internal CA, you must 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:

The alias used is the same in all of the previous examples, specifically for CSR. The my-ca-signed-cert.crt is what you should receive in response to a CSR.

It's 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

List KeyStore Contents

When debugging your KeyStore and client connections, it's 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.

Configure 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 instructions 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 it 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.

Generate 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, Contrast recommends using a reverse proxy. The following section walks you through enabling SSL in the Contrast server.

Import 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>

You may also 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.

Enable and configure HTTPS in the 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.

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