If you're a Managed Hosting (SaaS) customer, this topic doesn't apply to you.
Starting with the April 2014 release, Blackboard Learn 9.1 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. Blackboard Learn 9.1 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 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. You're responsible for working with a widely accepted vendor to purchase a certificate. Blackboard doesn't assist with purchase or renewal of your certificate. 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.
SSL serves to guarantee the authenticity of your server. Self-signed certificates such as the one installed by the Blackboard Learn installer do not provide a 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.
Blackboard 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
UNIX
Blackboard 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 bb-config.properties if the location of the original certificates was not known.
bbconfig.unix.ssl.ca.certificatefile=/usr/local/blackboard/apps/httpd/conf/ssl.crt/ca-bundle.crt
bbconfig.unix.ssl.certificatefile=/usr/local/blackboard/apps/httpd/conf/ssl.crt/server.crt
bbconfig.unix.ssl.certificatekeyfile=/usr/local/blackboard/apps/httpd/conf/ssl.key/server.key
- Navigate to the location of the existing certificates.
- 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
- A decode of the x509 certificate may be necessary to format it as pem
- When prompted type a password to protect exported certificate. (Make a note of this password as it will be required later)
- Copy the bb-certificates.pfx file to /usr/local/blackboard/config/keystores/
Windows
Export IIS TLS certificate
You can use the Microsoft Management Console (MMC) with the Certificates snap-in to export the entire certificate path: TLS server certificates, Intermediates certificates, and Trusted Root CA certificates.
More on exporting TLS Certificate on Windows Servers using MMC
IIS export of server certificate only
- Open IIS Manager and navigate to the server level.
- In Features View, double-click Server Certificates.
- Select a certificate and select Export from the Actions pane.
- In the Export Certificate dialog box, do the following:
- Select 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)
- Type a password in the Password box to protect exported certificate. (Make a note of this password as it will be required later)
Apply the exported certificate keystore to Blackboard Learn
The following steps only need to be performed if running tomcat only and not offloading TLS.
- Navigate to the blackboard configuration directory, such as ..\blackboard\config\, and make a backup copy of bb-config.properties.
Always backup the config file before making changes by copying it with the date of the change. For example: bb-config.properties.2014-04-21
- Copy the exported .pfx file to the keystores directory located in the blackboard config directory, e.g.:..\blackboard\config\keystores\
- Open bb-config.properties in a text editor such as vi or Notepad.
- Locate the Keystore section and add the details for the certificate
## Keystore configuration for HTTPS ##
bbconfig.appserver.keystore.filename=/usr/local/blackboard/config/keystores/bb-certificates.pfx
bbconfig.appserver.keystore.password=PASSWORD
bbconfig.appserver.keystore.type=PKCS12filename 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. - Save the bb-config.properties file.
To propagate the changes navigate to ..\blackboard\tools\admin and execute the PushConfigUpdates.sh|bat script.
Import a new commercial certificate to the 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 bb-config.properties file in the keystore section:
## Keystore configuration for HTTPS ##
bbconfig.appserver.keystore.filename=/usr/local/blackboard/config/keystores/tomcat.keystore
bbconfig.appserver.keystore.password=f973fac4a8bc6239aa83a8eb788d2a6a
bbconfig.appserver.keystore.type=JKS
bbconfig.appserver.keystore.key.alias=mydomain
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.
To find the alias name, run the following Java Keytool command from the JDK/bin folder:
keytool -list -v -keystore <full path to keystore>
Update the 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
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.
Import 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 provided cert.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 PushConfigUpdates.sh|bat script.
Import 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 PushConfigUpdates.sh|bat script.