HTTPS Support for the Enterprise Console

There is built-in HTTPS support for the Enterprise Console using a self-signed keystore file. The Enterprise Console supports either HTTP or HTTPS based on your choice during fresh installation or upgrade. You can reconfigure the Enterprise Console to revert from HTTPS back to HTTP, or vice versa, at any time.

About Enterprise Console SSL and Certificates

For the HTTPS client, the Enterprise Console packages the latest Mozilla truststore cacerts.jks, as it contains standard certificates. The Enterprise Console creates a keystore.jks file which contains a self-signed certificate. This certificate is imported into cacerts.jks during installation or upgrade.

For production use, we recommend that you replace the self-signed certificate with a certificate signed by a third-party Certificate Authority (CA) or your own internal CA.

This page describes how to:

enable HTTPS for the Enterprise Console during installation or upgrade.
update the certificate to a signed one.
customize keystore credentials.

Replacing the entire keystore is not recommended unless you first export the existing artifacts from the default keystore and import them into your own keystore.

It is also not recommended that you create your own self-signed certificate.

The exact steps to implement security typically vary depending on the security policies for the organization. For example, if your organization already has a signed certificate to use, such as a wildcard certificate used for your organization's domain, you can import it into the keystore using the Enterprise Console's update-certificate command. Otherwise, you can obtain a new one along with a certificate signing request.

Before Starting

On Linux machines, the Enterprise Console uses curl to check the responsiveness of the application URL. Therefore, SSL needs to have the latest NSS package to work.

For example, you can update the NSS package to the latest with the following command on CentOS:

yum update nss

Your update procedure or NSS package name may differ depending on your Linux operating system.

Enable Enterprise Console HTTPS for Fresh Installation

You can enable HTTPS during the Enterprise Console installation by selecting HTTPS as your preferred connection type:

Follow the steps to install the Enterprise Console:
- For GUI Installation, click the HTTPS checkbox.
  
  If the checkbox is left unselected, then the installation will default to HTTP.
  
  The Enterprise Console will create a self-signed certificate and use it for your HTTPS connection.
- For Silent Installation, edit the platform admin response varfile with the following parameter:
```
platformAdmin.useHttps$Boolean=true
```
  CODE
  This enables HTTPS connection and is the same as checking Enable Https Connection in the wizard installation option. Setting the parameter to false uses HTTP.
Optional: The Enterprise Console will create a self-signed certificate and use it for HTTPS connection. You can replace it with a certificate signed by a third-party CA. See Update to a Signed Certificate.

The Enterprise Console then configures the HTTPS protocol and disables HTTP in the Dropwizard configuration file, PlatformAdminApplication.yml. See the Dropwizard Configuration Reference for more information.

Example Enterprise Console HTTPS connector configuration:

server:
  type: simple
  connector:
    type: encrypted-https # encrypted-https is a customized HTTPS connector type in Enterprise Console, with keystore password encrypted.
    port: 9191 # DO NOT REMOVE alternatives are 8080
    keyStorePath: /appdynamics/platform-admin/conf/keys/keystore.jks
    keyStorePassword: s_-001-12-v/yKyIweuGQ=iLpBEDTqfP7vj++WP+MKEg==
    trustStorePath: /appdynamics/platform-admin/conf/keys/cacerts.jks
    trustStorePassword: s_-001-12-hdLwJEOZbns=kDmS/pLvq2A43iCWLJEcTg==
    certAlias: ec-server # DO NOT change cert alias name in keystore files.
    validateCerts: false
    supportedProtocols: [TLSv1.2]
    bindHost: 0.0.0.0
  applicationContextPath: /

The Enterprise Console encrypts all plain text passwords in the configuration file.

Enable Enterprise Console HTTPS for Upgrades

You can enable HTTPS from HTTP during upgrades from 4.4.3 to 4.5 and post-4.5 upgrades. You can also enable HTTPS for an existing Enterprise Console instance by reinstalling the Enterprise Console application:

Follow the steps to upgrade the Enterprise Console.
1. Change the platform admin response varfile with:
```
platformAdmin.useHttps$Boolean=true
```
  CODE
Complete the upgrade.
Optional: A self-signed certificate is created by the Enterprise Console and SSL is configured, just like it is with a fresh installation. You can replace it with a certificate signed by a third-party CA. See Update to a Signed Certificate.

When you upgrade your HTTPS supported Enterprise Console to future release versions, the Enterprise Console will follow the below protocols:

Upgrades with a self-signed certificate (the Enterprise Console installed certificate): The Enterprise Console will always recreate the new keystore.jks, with a new self-signed certificate in it, and update the cacerts.jks file with the new self-signed certificate under the <EC_installationDir>/conf/keys folder.
Upgrades with a signed certificate: The Enterprise Console will not modify your signed certificate, leaving it as it was before the upgrade.
Note: Do not change the serverHostName in the admin response varfile from a private IP/hostname (if you used a private IP/hostname as the serverHostName for a previous Enterprise Console fresh install or upgrade) to a public IP as the Enterprise Console will not support the signed certificate afterwards. This restriction only applies to upgrades with a signed certificate.
Upgrades with customized keystore/truststore path and passwords: The Enterprise Console will back up the .jks files only if they are under the <EC_installationDir>/conf/keys folder. The Enterprise Console will restore your keystore/truststore paths and passwords in PlatformAdminApplicationl.yml before the upgrade, even if you move the .jks files or change the password.

Changing the .jks files location is not recommended as they will not be backed up by the Enterprise Console if they are in another location.

Configure HTTPS for Enterprise Console in SAN Deployments

To configure HTTPS for the Enterprise Console deployed for a Subject Alternative Name (SAN) on AWS, you will need to generate keys from the san.cnf file. The instructions below show you how to enter multiple hostnames and aliases for the Enterprise Console in the san.cnf file and then generate the keys with it.

Create your san.cnf file for the SAN. In the following example san.cnf file, multiple domain names and aliases are defined in [ alt_names ].

[ req ]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext
prompt             = no
[ req_distinguished_name ]
countryName           = IN
stateOrProvinceName   = Karnataka
localityName          = Bangalore
organizationName      = Appdynamics
commonName            = ECserver
[ req_ext ]
subjectAltName = @alt_names
[alt_names]
DNS.1   = ECserver.com
DNS.2   = ECserver.secondary.com
DNS.3   = ECserver.alias1.com
DNS.4   = ECserver.alias2.com
IP.1        = 10.10.10.10
IP.2        = 10.10.10.9

Using the san.cnf file, generate the private key and CSR with the following openssl command:

openssl req -new -newkey rsa:2048 -nodes -out sslcert.csr -keyout private.key -config san.cnf

BASH

Check the CSR to confirm the SANs are correct:

openssl req -noout -text -in sslcert.csr | grep DNS
openssl req -noout -text -in sslcert.csr | grep IP

BASH

Sign the CSR by a certified authority (CA).

Update the certificate for the Enterprise Console:

./platform-admin.sh update-certificate --private-key <privateKeyfile> --ssl-cert <sslCertFile> --ssl-chain <sslChainfile1> <sslChainfile2> <...>

BASH

Customize Keystore Credentials

You can customize keystore credentials. The Enterprise Console preserves your customized keystore/truststore passwords.

To keep your customized files backed up, place them under the <EC_installationDir>/conf/keys directory. Placing your files anywhere besides <EC_installationDir>/conf/keys is not recommended because they may not be backed up.

If you change the keystore content for the Enterprise Console, you must re-run the change-keystore-password command and re-encrypt. Then, you need to restart the Enterprise Console. See Controller Secure Credential Store for more information.

Get Encrypted Password

You can update the password for the .jks files. If you do, you must also update the password in the PlatformAdminApplication.yml file.

Do not change the supportedProtocols in the PlatformAdminApplication.yml file.

To get an encrypted password:

- Make a note of the generated password to use in Step 4.

- For the keystore.jks file to work for the Enterprise Console, the storepass and keypass must be the same.

Use the Enterprise Console CLI to encrypt the new password:
```
./platform-admin.sh encrypt -t '<plain_text_password>'
```
Change the storepass in keystore.jks by using the <plain_text_password> from Step 1:
```
keytool -storepasswd -keystore keystore.jks
```
Change the ec-server keypass in keystore.jks by using the <plain_text_password> from Step 1:
```
keytool -keypasswd -alias ec-server -keystore keystore.jks
```
Use the encrypted password to update the Enterprise Console Dropwizard confirmation yml file (PlatformAdminApplication.yml) for the key "keyStorePassword".
Restart the Enterprise Console.

Update to a Signed Certificate

You can update the built-in self-signed certificate created by the Enterprise Console with a CA signed certificate from an eligible CA authority.

If you want to reuse the existing public key from the Java keystore to generate a CSR request, you must import the signed certificates manually. See step 6 to 9 in Create a Certificate and Generate a CSR for more information.

Most Linux distributions include OpenSSL. If you are using Windows or your Linux distribution does not include OpenSSL, you may find more information on the OpenSSL website.

Obtain a signed certificate:
1. Create a csr request.
  //Some CAs will create everything for you, including the private key. You may use the following keytool command to create a csr request from existing keystore.jks. keytool -certreq -alias ec-server -keystore keystore.jks -file AppDynamics.csr
  or
  //You can also use the following openssl command to create your own private key and csr request. openssl req -new -newkey rsa:2048 -nodes -out <name of csr request file>.csr -keyout <name of private key>.key -subj "/C=<custom>/ST=<custom>/L=<custom>/O=<custom>/OU=<custom>/CN=<hostname>"
2. Submit the certificate signing request file generated by the command (AppDynamics.csr in our example command) to your Certificate Authority of choice. When it's ready, the CA will return the signed certificate and any root and intermediate certificates required for the trust chain. The response from the Certificate Authority should include any special instructions for importing the certificate, if needed. If the CA supplies the certificate in text format, just copy and paste the text into a text file.
Run the Enterprise Console update certificate CLI command:
```
./platform-admin.sh update-certificate --private-key <privateKeyfile> --ssl-cert <sslCertFile> --ssl-chain <sslChainfile1> <sslChainfile2> ...
```
Refer to the following help points when running this command:
- The privateKeyfile, sslCertFile, and ssl-chain files do not have any file format restrictions. Any file format, such as .pkey and .txt, should work, as long as it is readable.
- The privateKeyfile file content must follow the PKCS8 format.
- sslCertFile is your SSL certificate file.
- ssl-chain files are additional certificates, such as intermediate certificates. These are optional, and you may provide as many of them as you would like.
This command updates the certificate in the keystore and truststore in the configuration yml file.
Restart the Enterprise Console for the new SSL configurations to take effect.

Verify the Use of SSL

You can test that your HTTPS support works by logging into the Enterprise Console GUI.

To make sure the configuration works, use a browser to connect to the Enterprise Console over the default secure port, port 9191:

https://<hosthame>:9191

CODE

Specify the hostname you used when you installed the Enterprise Console. The default port is 9191. This port needs to be exposed from your firewall rules so you can access the port from any place. See Port Settings for more information.

Make sure the Enterprise Console entry page loads in the browser correctly.

Depending on your browser, you may have to perform additional steps to verify your connection. For instance, for self-signed certificates on Chrome, you have to click to proceed. On Firefox, you have to create a security exception to proceed.

You can also verify that your configuration works by running commands on the Enterprise Console CLI.

Expired Certificate

In case of an expired certificate, the Enterprise Console CLI will still continue to work, but the CLI will also print out a warning, notifying you that the certificate has expired.

Upgrades to the Enterprise Console remain unaffected by expired certificates; when you try to upgrade the Enterprise Console without knowing that the certificate has expired, the upgrade should still succeed.

You can update the Enterprise Console self-signed certificate by reinstalling the application. For your own signed certificate, you can obtain a new one from CA and run the CLI command from Update to a Signed Certificate.

Revert the Enterprise Console to HTTP

You can fall back to HTTP from HTTPS support by reinstalling the Enterprise Console application.

Follow the steps to upgrade the Enterprise Console.
1. Change the platform admin response varfile with:
```
platformAdmin.useHttps$Boolean=false
```
  CODE
Complete the upgrade.

The Enterprise Console backs up any self-signed or signed certificate that is under <EC_installationDir>/conf/keys. However, if you manually move the keystore.jks and truststore.jks to your own location, then you will need to back up your customized certificates and SSL related files on your own before the upgrade.

Troubleshooting Common SSL Related Issues

This section covers a few of the most common Enterprise Console SSL related issues. It may help to enable -Djavax.net.debug=ssl in the platform-admin.sh execute CLI command section before troubleshooting.

Enterprise Console CLI Issue

If the installation or upgrade succeeds but the Enterprise Console CLI does not work, the CLI will remind you to check if the serverHostName you entered in the installer varfile is valid. The error will state that the Hostname %s not verified.

Certificates Without an Extension Field Issue

Certificates without an extension field, especially free signed certificates, will not work. They will lead to a KeyUsage error. Only signed certificates from an eligible CA authority should be used.

Enterprise Console Restart Issue

NSS package needs to be updated to the latest version on Linux machines. The Enterprise Console may not be able to restart if the NSS package is not updated to the latest version on Linux machines. See Before Starting for more information.