Setting up TLS to encrypt connections to Blackboard Learn does not secure the Collaboration Tool. The Collaboration Tool uses Apache™ Tomcat, not Apache™ HTTP Server or IIS, to handle user connections and serve pages. The Collaboration Tool uses a different hostname than the rest of the application. To avoid security warnings because the hostname is different, the Collaboration Tool requires using a separate TLS certificate.

As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that stores certificates. A self-signed certificate is a certificate created by you that is not submitted to a Certifying Authority. If you have a wildcard certificate for your domain, you can use it by importing it into the keystore for the collaboration server. The collaboration server is specified in apps/collab-server/http/tomcat/conf/server.xml.

Macintosh users running a Netscape or Internet Explorer browser will not be able to access the Collaboration Tool if a self-signed certificate is used to configure TLS. The Safari Web browser will work with a self-signed certificate.

If there are Macintosh users running Netscape or Internet Explorer browsers then use a signed certificate. If a signed certificate is preferred, see the Java documentation on keytools for information on obtaining a signed certificate and including it in the keystore.

In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing the Collaboration Tool and a self-signed certificate may be used. Certifying Authorities are used to prove to users of a Web site that the connection is secure and verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learn most likely do not require the validation of a third party before using the tool.

Configure the Collaboration Tool with a self-signed certificate

  1. Create a keystore.
  2. Configure Tomcat properties to use TLS encryption.

Configure the Collaboration Tool with a signed certificate

Clients who would like to use their existing TLS certificate should follow these steps.

  1. Convert the server.key and server.crt into a PKCS12 keystore using OpenSSL.

    openssl pkcs12 -export -out keystore.pkcs12 -in /path/to/server.crt

    -inkey /path/to/server.key

  2. This will prompt for a keystore password. The keystore will be created as keystore.pkcs12 in the current directory. Move this to an appropriate location.
  3. Use the keystore and certificate in the steps below that cover editing the bb-config.properties file so that Tomcat uses TLS.

Create the keystore

After creation, the keystore contains a self-signed TLS certificate specifically for Tomcat, <tomcat>.

To create the keystore and certificate, follow these steps:

  1. Log on to the Web/app server as the user that runs Blackboard Learn.
  2. Run the following from the command line:

    %JAVA_HOME%\bin\keytool -genkey -storetype pkcs12 -alias tomcat -keyalg RSA -keystore path_to_keystore

    The keystore will be created at the path_to_keystore.

  3. The first prompt asks for a password for the keystore. The default password that Tomcat expects is "changeit", but it is recommended that another password be used. Tomcat can be configured later to accept the new password.
  4. The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over TLS. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is:
    • First and Last Name
    • Organizational Unit
    • Organization
    • City or Locality
    • State or Province
    • Two-letter country code
  5. The last prompt asks for the password for the <tomcat> certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used.
  6. The keystore will be created in the specified directory.

Configure Tomcat to work with the TLS certificate

After creating the keystore and certificate, the last step is to edit the /blackboard/config/bb-config.properties file. Follow these steps to edit the file to work with TLS:

  1. Make a backup of the /blackboard/config/bb-config.properties file.
  2. Keep it safe so that the original settings can be restored.
  3. Open the bb-config.properties file in an editor.
  4. Find the following lines in the file and add the appropriate values.

    bbconfig.collabserver.keystore.filename=

    bbconfig.collabserver.keystore.password=

    bbconfig.collabserver.portnumber.ssl.default=8443

    bbconfig.collabserver.keystore.type=PKCS12

    The keystore.type must be set to PKCS12

  5. Save the file.
  6. Run PushConfigUpdates to apply the changes.
  7. Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the certificate. After accepting the certificate, the Collaboration Tool will open and communications will be secured using TLS encryption.