Skip to main content
Blackboard Help

Optional - TLS Configuration

Learn 9.1 April 2014 is based on an Apache™ Tomcat-only architecture, which no longer requires the installation of an HTTPD service (Apache or IIS). As a result, this release requires specific operating system configuration changes prior to installation that were not necessary for previous versions of Learn. Also note that TLS Choice is no longer an option in the user interface. Learn 9.1 April 2014 is TLS-only. If you had TLS Choice configured in a previous release, it will be turned off during the upgrade. Please read the Install Learn or Upgrade Learn topics completely before proceeding.

Why TLS?

Transport Layer Security (TLS) is a standard technology behind establishing an encrypted connection between systems, such as a web server (host, in this case, your Learn installation) and a web browser (client, in this case, your faculty and students). This encrypted connection between the two systems makes sure that all the data passed between them remains private, with explicit sender and receiver identification.

TLS is the successor of Secure Sockets Layer (SSL).

TLS is an industry standard and is used by millions of websites to protect their online transactions ensuring the privacy of the data in transmission. If you have ever visited a website using the https:// you communicated with the service using a secure connection via TLS.

TLS requires a certificate to be installed for a trusted encrypted connection to take place. Certificates may be purchased from various vendors. Purchase certificates from a widely accepted vendor. Otherwise, certificate warnings may hamper client access to systems.

This help topic is for installing TLS certificates in replacement of the Learn self-signed certificate in a Learn-Only configuration. If you are using TLS-Offloading via a web server see Optional - Front Learn with a Webserver. If you are using TLS-Offloading via a Load Balancer see Optional - Set Up Load Balancing for Multiple Application Servers.

TLS serves to guarantee the authenticity of your server. Self-signed certificates such as the one installed by the Blackboard Learn installer do not provide an TLS required chain of trust. Chain of trust provides the Certificate Authority which guarantees the authenticity of the certificate identifying the server. For this reason a non-commercial self-signed certificate is not suitable for connecting to Safe-Assign or Blackboard Cloud Services which require a commercial Certificate Authority.

Learn and TLS

Starting with Learn April 2014 release, Full TLS is a requirement. Most of the information transmitted between Learn and the end user contains personal data or other sensitive information. When a TLS certificate is used, the information becomes unreadable to everyone except the those legitimately accessing the service.

Learn installs and upgrades with a default set of self-signed certificates.

For best performance, TLS should ideally be handled by the Load Balancer utilizing TLS Offloading. TLS Offloading is where the load balancer communicates with the client using HTTPS but decrypts the sessions and communicates with the Blackboard Application Servers using HTTP over a secure or private network.

Details for configuring TLS in a load balanced environment are outlined in the Post-Installation and Upgrade section: Optional - Set Up Load Balancing (Multiple Application Servers)

On single server systems or where TLS offload is not possible, commercial TLS certificates can be applied directly to tomcat.

If the institution is upgrading and currently has a commercial TLS certificate deployed in Apache HTTP Server or IIS, these need to be exported and re-applied to Learn once the updater has completed.

Details for configuring TLS in a Web Fronted environment are outlined in the Post Installation and Upgrade section: Optional - Front Learn with a Webserver

Export Existing TLS Certificates


Learn now uses a keystore format. The existing commercial certificates need to be combined into a keystore to be applied to Learn.

After upgrade if a directory inside /usr/local/blackboard was used for the location of the existing certificate files, these will be in the backups directory after the install has completed. (for example /usr/local/blackboard/backups/20140328-120821/apps/httpd/conf/). This directory also has a copy of the old if the location of the original certificates was not known.

  1. Navigate to the location of the existing certificates.
  2. Use openssl to create a keystore from the existing bundles.
    • A decode of the x509 certificate may be necessary to format it as pem

      openssl x509 -inform der -in ./ssl.crt/server.crt -out server.pem

    • Use openssl to create a PKCS12 keystore passing in the certificate file, certificate key and any intermediate certificate bundles.

      openssl pkcs12 -export -in server.pem -inkey ./ssl.key/server.key -certfile ./ssl.crt/ca-bundle.crt -out bb-certificates.pfx

  3. When prompted type a password to protect exported certificate. (Make a note of this password as it will be required later)
  4. Copy the bb-certificates.pfx file to /usr/local/blackboard/config/keystores/


Export IIS TLS certificate

Option 1 - IIS Export

  1. Open IIS Manager and navigate to the server level.
  2. In Features View, double-click Server Certificates.
  3. Select a certificate and click Export from the Actions pane.
  4. In the Export Certificate dialog box, do the following:
    1. Click the browse button (…) to navigate to C:\blackboard\config\keystores\ and enter the name of a file in which to store the certificate for exporting.(E.g bb-certificates.pfx)
    2. Type a password in the Password box to protect exported certificate. (Make a note of this password as it will be required later)

Option 2 - The Microsoft Management Console (MMC) with the Certificates snap-in may alternatively be used to view and manage TLS server certificates, Intermediates certificates, and Trusted Root CA certificates.

See - Exporting TLS Certificate on Windows Servers using MMC

Apply the Exported Certificate Keystore to Learn

The following steps only need to be performed if running tomcat only and not offloading TLS.

  1. Navigate to the blackboard configuration directory, e.g.: ..\blackboard\config\, and make a backup copy of

    Always backup the config file before making changes by copying it with the date of the change. For example:

  2. Copy the exported .pfx file to the keystores directory located in the blackboard config directory, e.g.:..\blackboard\config\keystores\
  3. Open in a text editor such as vi or Notepad.
  4. Locate the Keystore section and add the details for the certificate

    ## Keystore configuration for HTTPS ##

    filename The full path to the exported certificate file.
    password The password chosen when the keystore was created
    type The keystore type. Type=PKCS12 for Certificates exported from Windows or keystores created using openssl.
  5. Save the file.

To propagate the changes navigate to ..\blackboard\tools\admin and execute the|bat script.

Importing a New Commercial Certificate to the Learn Keystore

Certificates need to be renewed and replaced. The Java Keytool is a key and certificate management utility. Java Keytool stores keys and certificates in a keystore. A Keytool keystore contains the private key and any certificates necessary to complete a chain of trust and establish the trustworthiness of the primary certificate. The Learn keystore is in the blackboard/config/keystore directory and is named tomcat.keystore. This file is referenced in the file in the keystore section:

## Keystore configuration for HTTPS ##

Changing the name of the keystore requires updating the filename, password, and type when using a keystore other than the one provided by the Learn installer. The default type for keytool created keystores is JKS, use for PKSC12 for those created with OpenSSL.

You must provide the full certificate chain - this includes importing intermediate certificates.

Updating the Learn Keystore

Each certificate in a Java keystore is associated with a unique alias. When creating a Java keystore you first create the .jks file that will initially only contain the private key. You will then generate a CSR and request a certificate generated from it from your certificate vendor. Then you will import the certificate to the keystore including any root certificates as provided from the vendor

Before continuing backup the installed tomcat.keystore file to tomcat.keystore.backup. If there are issues with the process you may restore TLS by copying tomcat.keystore.backup to tomcat.keystore. Also in some cases an application other than keytool may have been used to generate the keystore, private.key, or certificate signing request. In this situation the private.key and signed certificate must be combined into a PKCS12 keystore and imported.

Generate a certificate signing request (CSR) for the blackboard keystore and submit the CSR to your certificate vendor. On receiving your certificate you will import it into the Learn keystore.

keytool -certreq -alias "mydomain" -keystore blackboard/config/keystore/tomcat.keystore -file mydomain.csr

Import the Signed Certificate into the Learn Keystore

Use the keytool to import the vendor provided certificate. Always follow certificate vendor recommendations for installation of purchased certificate trust chains in a Tomcat environment keystore.

Importing Certificates Created from Non-keystore Generated CSRs

If the CSR was generated from an external private.key then you must create a PKCS12 store containing the private.key as the keytool does not support the direct importing of private keys. Use OpenSSL to create a PKCS12keystore containing your private key and issued certificate and import the PKCS12 keystore into the existing Learn keystore or replace the existing Learn Keystore.

If you have private.key and certificate authority providedcert.crt in PEM format, these need to be exported into pkcs12 format:

openssl pkcs12 -export -in cert.crt -inkey private.key -certfile cert.crt -name "Commercial" -out keystore.p12

Import the p12 keystore:

keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore tomcat.keystore -deststoretype JKS

To propagate the changes navigate to ..\blackboard\tools\admin and execute the|bat script.

Importing Certificates Created from keystore Generated CSRs

If your CSR was generated using the original Learn provided keystore or a new keystore created with the keytool you only need to import the crt as the private key is already contained in the keystore:

keytool -import -trustcacerts -alias mydomain -file cert.crt -keystore blackboard/config/keystore/tomcat.keystore

To propagate the changes navigate to ..\blackboard\tools\admin and execute the|bat script.