Edge Documentation

Creating a Secure AppBoard/enPortal Server

AppBoard/enPortal is distributed with an invalid dummy SSL certificate for its Tomcat web server. This allows the system to function, but the client web browser will warn the user if one or more issues are identified with regard to the web server certificate:

• The certificate has expired.
• The certificate is not applicable to the server.
• The certificate is not signed by an authorized Certificate Authority.

Selecting a Certificate Authority

A certificate for your web server must be signed by a Certificate Authority that is trusted by your web browser. There are many such authorities and most provide detailed assistance for obtaining a signed server certificate. When selecting an authority, be aware of the following points:

• You need to obtain a signed Apache mod_ssl server certificate.
• You may need to provide physical documentation to the Authority to establish proof of identity.
• You need to renew certificates periodically (at least every 2 years). Renewal activities are typically less involved than origination activities.

Generating a Certificate Signing Request (CSR)

If you are running Tomcat behind another web server, such as Apache or Microsoft IIS, you need to configure the primary web server to handle the SSL connections from users. This primary server will negotiate all SSL-related functionality, then pass on any requests destined for the Tomcat container only after decrypting those requests.

In order to configure Tomcat standalone for SSL support, you need to create (or import) an SSL certificate. An OpenSSL utility is used to generate Certificate Signing Requests (CSRs) and certificates. Download the OpenSSL utility and generate a CSR. You must then submit the CSR to your Certificate Authority.

Installing the Certificate Files on the AppBoard/enPortal Server

Install the private key generated by the openssl tool. Copy the server.key file to the following location on your AppBoard/enPortal server:

/server/conf/ssl.key/

When your Certificate Authority provides you with a signed certificate, copy the file to the following location on your AppBoard/enPortal server:

/server/conf/ssl.crt/

You must re-start the enPortal web server after installing these files.

Creating Intermediate CA Certs

An intermediate certificate is the certificate, or certificates, that go between your site (server) certificate and a root certificate. The intermediate certificate, or certificates, completes the chain to a root certificate trusted by the browser.

Using an intermediate certificate means that you must complete an additional step in the installation process to enable your site certificate to be chained to the trusted root, and not show errors in the browser when someone visits your web site.

For instructions on the process of creating Intermediate CA Certs, please see the Intermediate CA Certs page.

Configuring AppBoard/enPortal for HTTPS

Perform the following steps to configure AppBoard/enPortal to use your SSL certificate and run under HTTPS:

AppBoard/enPortal ships with a sample certificate that you can use for testing purposes. If you run the following steps, without completing the steps outlined above under "Installing the Certificate Files on the AppBoard/enPortal Server", the sample certificate will be used.

1. Add the following lines to /server/bin/setenv-custom.bat (Windows) or /server/bin/setenv-custom.sh (Linux)
   • set HTTP_PORT=443
   • set HTTP_SSL=true
2. [Optional] Add the following additional configuration lines:
   • set KEYSTORE_FILE=conf/ssl.crt/tomcat.crt
     • (location of certificate file)
   • set KEYSTORE_PASS=enportal
     • (password of certificate file)
   • set KEYSTORE_TYPE=JKS
     • (type of certificate, must be either "JKS" - default Java Key Store - or "PKCS12")

Some applications, such as Skype, run on port 443. If you see the error message "Error 107 (net::ERR_SSL_PROTOCOL_ERROR): SSL protocol error" in your browser, check to make sure you do not have any other applications running on port 443 prior to starting Tomcat with the startup command

Installing Certificate Files on a Mobile Client Device

When using an iOS device to connect to an AppBoard server running on SSL, if the site has an SSL certificate that is self-signed or otherwise non-trusted, there may appear to be no way to work around it or accept the cert manually. In this case, perform the following steps to register the certificate on the mobile device:

1. On the desktop, use a Firefox browser to navigate to the site (for example, https://www.myappboardserver.com/).
2. Click on the "lock" icon next to the address bar to view the certificate.
3. Use the certificate viewer to view the certificate for "www.myappboardserver.com".
4. Click on the "Export..." button to export the certificate. Use the default format (X.509 Certificate (PEM) (*.crt;*.pem).
5. By default, the certificate is saved as "www.myappboardserver.com.crt".
6. Use an email client on the desktop to send yourself an email attached with the certificate file. (Note: Gmail might block sending that file. Yahoo Mail is a suggested alternative.)
7. On the iOS device, use the iOS Mail program to open up that email.
8. Click on the attached certificate and you will be prompted for installing the certificate.
9. Click on "OK" to install the certificate.

Now, appboard on that iOS device will be able to connect to the "www.myappboardserver.com" server.