If you are a Managed Hosting customer, this topic doesn't apply to you.

There may be workflows that require Learn to be fronted by a Webserver. One such workflow is the use of a web delegated authentication service like Shibboleth.

TLS and institutional security policies: Learn-Only may be configured to support commercial TLS certificates eliminating the requirement for a webserver provided TLS configuration. A Learn-Only installation simplifies management of the Learn environment and eliminates the webserver as a potential point of failure. See TLS Configuration for details.

Note that bbconfig.ssl.offloaded and bbconfig.ssl.offloaded.hostname tags are no longer necessary for offloading TLS and have been removed from bbconfig. TLS offloading is now indicated via inclusion of the x-forwarded-proto in requests.

Front Blackboard Learn with Apache™ HTTP Server

Starting with Learn 9.1 April 2014, Blackboard Learn no longer supports Apache 1.3 web server. If your deployment requires a web server, Apache 2.2 can be used. Apache 2.2 is required if Shibboleth authentication provider is used.

Learn may be configured to run on a system administrator or default operating system installed Apache 2. Installation of Apache 2 may be done to support institutional security policy while enabling the use of the RHEL approved and secured version of Apache 2. Blackboard supports only the official versions of Apache.

Apache 2 additionally provides convenient configuration support for Integrating Shibboleth.

It is useful to ensure that you have a functioning webserver prior to connecting it to Blackboard Learn. Installing and testing the webserver alone helps isolate potential issues.

Configure the Apache HTTP Server

To properly handle the required request forwarding from Apache to Learn it is necessary to ensure that all requests are forwarded to Blackboard Learn.

Perform the steps outlined in the apache2 README located in ~blackboard/config/apache2/README.txt:

  1. Create a symlink from your Apache 2.2 distribution's conf.d directory to the blackboard.conf configuration file in this directory:

    cd /etc/httpd/conf.d
    sudo ln -s /usr/local/blackboard/config/apache2/blackboard.conf

  2. Edit /usr/local/blackboard/config/apache2/blackboard.conf.bb and add:

    UseCanonicalName Off
    ServerName learn.example.com
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8081/
    ProxyPassReverse / http://127.0.0.1:8081/

    The ServerName will bb-config.frontend.hostname and will be the default hostname end users access the service on. The port in the Proxy configuration will match the bbconfig.appserver.http-proxy.portnumber tag in the bb-config.properties. By default this is 8081.

TLS is required by Learn at the point of access by end users so the Blackboard Learn installation of Apache Tomcat will be aware the session is not secure and redirect to the Apache Tomcat secure port of 8443.

TLS must be configured at the point of access by end users as shown below.

If a Load Balancer will be the point of access by end users TLS would be configured there and the Load Balancer pool would point to the Apache Server running on port 80. Proceed with Optional - Setup or Update Shibboleth or Set Up Load Balancing for Multiple Application Servers.

If Apache will be the point of access by end users proceed with Configuration of Webserver-based TLS before Optional - Setup or Update Shibboleth.

Configure Webserver-based TLS (optional)

You may optionally use the TLS capabilities of the Webserver to handle encryption and decryption of server traffic.

If you previously added port prerouting to your iptables (as described in the Optional - Set Up Port Forwarding for a Single Application Server) these settings must be commented out for use of a webserver fronting Learn. You must also open port 443. Ports 8080 and 8443 may be closed.

Apache HTTP Server

Install your TLS certificates to be accessed by the Apache HTTP service. Generally these are provided by your certificate vendor, the below are provides the additional steps necessary for proper configuration with Learn.

It is useful to configure Apache HTTP Server TLS without Learn running. After TLS is configured and working correctly with the Apache HTTP Server, restart the Learn service.

After upgrade if a directory inside /usr/local/blackboard was used 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.

In this example edits will be made to the default install Apache HTTP Server /etc/httpd/conf.d/ssl.conf file and focus on configuration of the _default_:443 SSL <VirtualHost> block.

  1. If previously linked, delete the blackboard.conf symbolic link from /etc/httpd/conf.d. This only needs to be done if TLS is handled by the Apache HTTP Server.

    rm /etc/httpd/conf.d/blackboard.conf

  2. Open /etc/httpd/conf.d/ssl.conf for editing
  3. Find and edit the SSLCertificateFile path to reflect where you have stored the server cert

    SSLCertificateFile /etc/httpd/conf/certificates/server.cert

  4. Find and edit the SSLCertificateKeyFile path to reflect where you have stored the server key

    SSLCertificateKeyFile /etc/httpd/conf/certificates/server.key

  5. Find and edit the SSLCertificateChainFile path to reflect where you have stored the intermediate certificate if this was provided by your certificate vendor

    SSLCertificateChainFile /etc/httpd/conf/certificates/vendorCA.crt;

    If an intermediate certificate was not provided this may remain commented out or try pointing this element to the SSLCertificateFile. Consult your certificate vendor's certificate installation instructions.

  6. SSLCACertificateFile may be left commented out. Consult your certificate vendor's certificate installation instructions.

  7. Add the following Rewrite Rule at the end of the file. This rewrite rule consistently sets the http protocol to HTTPS which is necessary for correct port forwarding under TLS.

    # Rewrite all incoming requests to HTTPS (port 443)
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
    #end HTTPS Rewrite Rules

  8. Save the ssl.conf file
  9. Restart Apache 2:

    sudo apachectl restart

  10. Test the configuration by entering the URL to the server in a browser.

    Only on a successful TLS test proceed to the next step.

    Entering HTTP://<server> should redirect to HTTPS://<server> and load the default Apache HTTP server start page.

    Entering HTTPS://<server> should load the default Apache HTTP server start page.

    This verifies that TLS certificates are installed correctly.

  11. Re open /etc/httpd/conf.d/ssl.conf for editing and above the (last) line containing the closing </VirtualHost> tag add:

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8081/
    ProxyPassReverse / http://127.0.0.1:8081/
    RequestHeader set X-Forwarded-Proto "https"

  12. Restart Apache 2:

    sudo apachectl restart

    Apache will now be running HTTPS on port 443 and proxying to port 8081 on the Blackboard Learn installation of Apache Tomcat.
  13. Learn will not attempt to start or stop the Apache HTTP Server. Apache must be managed separately.

Learn

If the frontend port and protocol were not set at first installation, these must be updated to match Apache, IIS default website, or Load Balancer details.

  1. Open bb-config.properties in a text editor such as vi or Notepad.
  2. Locate the bbconfig.frontend section and add the details for the Frontend.

    bbconfig.frontend.fullhostname=<server hostname>
    bbconfig.frontend.portnumber=443
    bbconfig.frontend.protocol=https

    Learn requires TLS at the point of access by users. If Apache or IIS is the point users access the service, these options need to match Apache/IIS. If the Load Balancer is the point of access by users, options need to match the Load Balancer.

  3. Restart Learn and propagate the changes by executing:

  4. /usr/local/blackboard/tools/admin/PushConfigUpdates.sh

Front Blackboard Learn with IIS

Learn may be configured to run with IIS acting as a proxy. This is required to run authentication extensions such as Shibboleth.

Fronting Learn with IIS requires the IIS default website exists. If the default website does not exist, recreate it as follows:

  1. Open IIS Manager
  2. Right-click on Sites folder and select Add Web Site...
  3. Under Site name, type Default Web Site
  4. Under Application pool, select DefaultAppPool
  5. Under Physical path type C:\Inetpub\wwwroot
  6. Select OK
  7. Restart IIS to complete the process

To restart IIS, open a cmd prompt and execute:

IISRESET

If IIS will be serving users directly, not via a load balancer, the TLS certificate must be applied to IIS.

To configure TLS for IIS, follow the IIS Manager section of the following Microsoft document. How To Set Up TLS on IIS

To front Learn with IIS, an IIS module needs to be added. This module acts as a proxy server, forwarding requests onto the application servers.

Download and install Microsoft Application Request Routing extension from iis.net Download Application Request Routing

Follow the installation instructions.

Once installation has completed, the proxy module must be enabled.

For simplicity, configuration is done using appcmd.exe.

  1. Open a cmd prompt
  2. Navigate to the %systemroot%\system32\inetsrv\ directory and execute the following commands:

    appcmd.exe set config -section:system.webServer/proxy -enabled:true

    appcmd.exe set config -section:system.webServer/proxy /preserveHostHeader:"True" /commit:apphost

    appcmd.exe set config -section:system.webServer/proxy /reverseRewriteHostInResponseHeaders:"False" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/allowedServerVariables /+"[name='HTTP_X_FORWARDED_PROTO']" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='LearnProxy',patternSyntax='Wildcard']" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='LearnProxy'].serverVariables.[name='HTTP_X_FORWARDED_PROTO',value='https']" /commit:apphost

    appcmd.exe set config -section:system.webServer/proxy /includePortInXForwardedFor:"False" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='LearnProxy'].conditions.[input='{HTTPS}',pattern='on']" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='LearnProxy'].match.url:*" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='LearnProxy'].action.type:Rewrite" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='LearnProxy'].action.url:http://127.0.0.1:8081/{R:0}" /commit:apphost

    The action.url should be an ipv4 address, using a hostname will default to ipv6 which has been noted as having significantly slower throughput.

    The port in the action.url will match the bbconfig.appserver.http-proxy.portnumber tag in the bb-config.properties. By default this is 8081

  3. A rule to redirect http to https also needs to be added so that users are forced to use TLS.:

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='HTTP to HTTPS redirect',patternSyntax='Wildcard']" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='HTTP to HTTPS redirect'].match.url:*" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='HTTP to HTTPS redirect'].conditions.[input='{HTTPS}',pattern='off']" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='HTTP to HTTPS redirect'].action.type:Redirect" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='HTTP to HTTPS redirect'].action.redirectType:Found" /commit:apphost

    appcmd.exe set config -section:system.webServer/rewrite/globalRules /"[name='HTTP to HTTPS redirect'].action.url:https://{HTTP_HOST}/{R:1}" /commit:apphost

Set the frontend port and protocol

If the frontend port and protocol were not set at first installation, these must be updated to match Apache, IIS default website, or Load Balancer details.

  1. Open bb-config.properties in a text editor such as Notepad.
  2. Locate the bbconfig.frontend section and add the details for the Frontend.

    bbconfig.frontend.fullhostname=<server hostname>
    bbconfig.frontend.portnumber=443
    bbconfig.frontend.protocol=https

    Learn requires TLS at the point of access by users. If Apache or IIS is the point users access the service, these options need to match Apache/IIS. If the Load Balancer is the point of access by users, options need to match the Load Balancer.

  3. Restart Learn and propagate the changes by executing:

    /usr/local/blackboard/tools/admin/PushConfigUpdates.bat