Appboard/2.5/admin/ssl configuration: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
No edit summary
Line 9: Line 9:
== Configuring AppBoard for SSL ==
== Configuring AppBoard for SSL ==


To enable HTTPS (HTTP over SSL) mode use the <tt>HTTP_SSL</tt> runtime option and set it to <tt>true</tt>. In addition you may want to also change:
The overall process involves:


* <tt>HTTP_PORT</tt>: HTTPS is typically served on port 443
# Obtaining a signed certificate:
* <tt>KEYSTORE_FILE</tt>: if using your own certificate
## Pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
* <tt>KEYSTORE_PASS</tt>: if using your own certificate
## Create a private key and Certificate Signing Request (CSR)
* <tt>KEYSTORE_TYPE</tt>: if using your own certificate
## Have the CA sign the request
## Download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
# Alternatively create a self-signed certificate. However, end-users will be presented with certificate errors and warnings as the certificate is not signed by a trusted authority.
# Create a Java KeyStore (JKS) from the private key, signed certificate, and any intermediate certificates from the CA.
# Install they keystore file on the AppBoard server.


See the [[appboard/2.5/admin/runtime_options|Runtime Options]] page for more information on these settings and how to configure them. After making any changes then restart the AppBoard service.
{{Note|Due to the large variety of certificate authorities and key/certificate formats, this documentation cannot cover all options. If following instructions found elsewhere make sure to install the resulting keystore correctly for AppBoard (see the ''Install the Keystore'' section).}}
 
{{Warning|Do not configure SSL by editing the AppBoard server.xml file as this is a system file and replaced on upgrade. The correct way is to edit the runtime options.}}
 
=== Process Overview ===
 
The basic process is:
 
# pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
# create a Certificate Signing Request (CSR)
# have the CA sign the request
# download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
# create a Java KeyStore (JKS) file for Tomcat and install on the AppBoard server.
 
Another option is to generate a self-signed certificate to replace the self-signed certificate Edge ships with AppBoard. However, end-users will still be presented with certificate errors and warnings.


=== Creating Certificate & Keystore ===
=== Creating Certificate & Keystore ===
Line 52: Line 42:
# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.
# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.


=== Installing the Keystore ===
=== Enable SSL & Install the Keystore ===


Once a valid keystore has been created it can be installed on the AppBoard server:
Once a valid keystore has been created it can be installed on the AppBoard server:


# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.
# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.
# Edit <tt>setenv-custom.sh|.bat</tt> and update the <tt>KEYSTORE_FILE</tt>, <tt>KEYSTORE_PASS</tt>, and <tt>KEYSTORE_TYPE</tt> as required. If using the instructions above then the type should not need to be changed. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>
# Edit <tt>setenv-custom.sh|.bat</tt> and:
# As noted previously also make sure the <tt>HTTP_SSL</tt> option is set to <tt>true</tt>.
## update the <tt>KEYSTORE_FILE</tt> and <tt>KEYSTORE_PASS</tt> as required. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>
## update the <tt>KEYSTORE_TYPE</tt> if using something other than Java KeyStore (JKS) format.
## set the <tt>HTTP_SSL</tt> option to <tt>true</tt>.
## (optionally) set the <tt>HTTP_PORT</tt> to the desired port.
# Restart the AppBoard server.
# Restart the AppBoard server.
See the [[appboard/2.5/admin/runtime_options|Runtime Options]] page for complete information on all runtime options.





Revision as of 08:05, 20 March 2015

Overview

For security reasons it's recommended to run AppBoard over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the AppBoard server are encrypted.

By default AppBoard is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.

Configuring AppBoard for SSL

The overall process involves:

  1. Obtaining a signed certificate:
    1. Pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
    2. Create a private key and Certificate Signing Request (CSR)
    3. Have the CA sign the request
    4. Download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
  2. Alternatively create a self-signed certificate. However, end-users will be presented with certificate errors and warnings as the certificate is not signed by a trusted authority.
  3. Create a Java KeyStore (JKS) from the private key, signed certificate, and any intermediate certificates from the CA.
  4. Install they keystore file on the AppBoard server.
Template-note.png
Due to the large variety of certificate authorities and key/certificate formats, this documentation cannot cover all options. If following instructions found elsewhere make sure to install the resulting keystore correctly for AppBoard (see the Install the Keystore section).

Creating Certificate & Keystore

For SSL Tomcat requires a Java KeyStore (JKS). The keystore needs to contain the private key, the signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the keytool command.

The recommended approach is to use keytool to create the private key and CSR and keystore all in one go, then have the CA sign, and then import the signed certificate using PKCS#7 format directly into the keystore. This process is well outlined in the VeriSign documentation below:

  1. creating a CSR and submitting for signing (using keytool and creating a keystore in the process).
  2. importing the signed certificate into a JKS keystore (in PKCS#7 / .p7b format)
  3. Then follow the instructions below on Installing the Keystore.

However, if you already have an existing private key, signed certificate, and intermediate certificates in X.509 format then some conversion is required before importing into a JKS. This process will require openssl.

  1. Convert the private key (private.key), signed certificate (server_signed.crt), and intermediate certificates (ca.crt) into PKCS#12 format:
    openssl pkcs12 -export -in server_signed.crt -inkey private.key -CAfile ca.crt -caname root -chain -out combined.p12 -name your-alias
    You will be prompted to enter a password, make sure you set a password (do not leave blank). If you do not have any intermediate certificates then leave out the -CAfile, -caname, and -chain options.
  2. Create a JKS from the combined.p12 file generated above:
    keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias your-alias -destkeystore your-keystore.jks
    You will be prompted for the password set above and a new password, you must use the same password. your-alias must match the alias set in step (1).
  3. Take the resulting JKS file (your-keystore.jks) and follow the instructions below on Installing the Keystore.

Enable SSL & Install the Keystore

Once a valid keystore has been created it can be installed on the AppBoard server:

  1. copy to the [INSTALL_HOME]/server/conf/ssl.crt/ directory. By default files in this directory are automatically included in full archives.
  2. Edit setenv-custom.sh|.bat and:
    1. update the KEYSTORE_FILE and KEYSTORE_PASS as required. Please note the keystore file path is relative to [INSTALL_HOME]/server/
    2. update the KEYSTORE_TYPE if using something other than Java KeyStore (JKS) format.
    3. set the HTTP_SSL option to true.
    4. (optionally) set the HTTP_PORT to the desired port.
  3. Restart the AppBoard server.

See the Runtime Options page for complete information on all runtime options.


Redirecting HTTP traffic

There are two recommended approaches for redirecting standard HTTP traffic to HTTPS:

  1. Use an external tool to redirect the traffic such as a load balancer or a full featured HTTP server like Apache. For many this will be the preferred option as since no configuration changes to enPortal/AppBoard are necessary.
  1. Modify server/conf/server.xml and server/webapps/enportal/WEB-INF/web.xml to define an extra non-SSL connector that will redirect to the HTTPS port. This approach is well documented by the Tomcat user community.

Additional Topics