Setting up TLS to encrypt connections to Blackboard Learn does not secure the Collaboration Tool. The Collaboration Tool uses Apache™ Tomcat, not Apache™ 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 Netscape, Internet Explorer, or Safari may use self-signed certificates to configure TLS. A pop-up warning may appear during the process; select Continue to complete the process.

If users would prefer to use a signed certificate see the Java documentation on keytools for information about 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. 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.

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.

    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 following file:

    blackboard\config\bb-config.properties

  2. Keep it safe so that the original settings can be restored.
  3. Open the bb-config.properties file in Notepad or an XML 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.