Download PDF
Download page HTTPS Support for the Enterprise Console.
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, AppDynamics strongly recommends 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
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
CODEThis 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: /
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.
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 thecacerts.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 theserverHostName
in the admin response varfile from a private IP/hostname (if you used a private IP/hostname as theserverHostName
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 inPlatformAdminApplicationl.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 examplesan.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 followingopenssl
command:openssl req -new -newkey rsa:2048 -nodes -out sslcert.csr -keyout private.key -config san.cnf
BASHCheck 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
BASHSign 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.
<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
inkeystore.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:
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>"
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,
andssl-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.
- The
- 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
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.
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.