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

The Shibboleth initiative is developing an open, standards-based solution to meet the needs for organizations to exchange information about their users in a secure, privacy-preserving manner. This topic provides a brief overview of Shibboleth and explains how it is installed on Blackboard Learn.

Shibboleth is a single sign-on system that authenticates visitors to a website by accessing information stored on the user's security domain. This permits users to access controlled information securely from anywhere without additional passwords or needlessly compromising privacy. For example, if a student is taking classes at two universities, and both schools use Shibboleth, the student may have a single username and password to access information at both universities' websites.

Shibboleth is fully supported as a custom authentication option for Blackboard Learn on Linux operating systems. Because of the experimental nature of the underlying Shibboleth technologies and limited operational expertise available for Shibboleth, Blackboard recommends that customers consider running a restricted pilot implementation on a test or development server before making this feature generally available on their systems.

Before configuring the Shibboleth server, Blackboard Learn users using the same username or batch Uid that will be passed back to Blackboard Learn using the REMOTE_USER environment variable must exist.

Blackboard Learn's Shibboleth integration allows the Shibboleth Identity Provider (IdP) to be used for initial authentication while leaving Blackboard Learn in charge of session management. The advantages include:
Only pages that actually require authorization are sent over to Shibboleth for authentication. Guest access continues to work properly.
Using multiple authentication types on the Blackboard Learn server.

To accomplish this, Shibboleth provides a single URL deep within Blackboard Learn that users are redirected to when authentication is needed. This URL is the only one that Shibboleth restricts access to.

About Shibboleth

Clients upgrading from an earlier version of Blackboard Learn will need to reconfigure Shibboleth after the upgrade has completed.

The next two sections explain how to install Shibboleth and how to set up Shibboleth with Blackboard Learn on both Linux and Windows . These instructions apply only to setting up Blackboard Learn as a Shibboleth target.

Installation of Shibboleth Authentication Integration with Blackboard Learn requires that a functional Shibboleth installation. To install Shibboleth Integration follow the steps in the sections appropriate for the operating system.

Shibboleth integration is performed using the native Shibboleth Provider (SP) software and mod_shib Apache module.

If you are load balancing your Shibboleth configuration you must configure the Load balancer to proxy to port 80 on the web server which will forward requests to Learn port 8081 - Load Balancer:443 -> Web server:80 -> Learn:8081."

Front the application server with Apache™ HTTP Server or IIS

A key component of a Shibboleth Authentication Integration is the installation of a Webserver (Apache 2 or IIS). To learn more about running a Webserver for Blackboard Learn see Optional - Front Learn with a Webserver.

Fronting Learn with a webserver is a prerequisite to continuing the installation of Shibboleth.

Install native Shibboleth provider

The Shibboleth documentation describes the basic procedure for installing and configuring a native SP. It is likely that the institution has specific configuration options that need to set here to integrate correctly with the Identity Provider (IdP).

Shibboleth Installation Documentation

UNIX

After completing and testing the prerequisite of Front Learn with a Webserver, a Shibboleth-specific change is required. The default Blackboard Learn configuration uses a Proxy rule to tunnel all URLs through to Tomcat. The Shibboleth URLs need to be excluded so that they are handled internally by mod_shib or isapi_shib.dll:

echo 'ProxyPass /Shibboleth.sso !' > /etc/httpd/conf.d/10_shib_excludes.conf
echo 'ProxyPass /shibboleth-sp !' >> /etc/httpd/conf.d/10_shib_excludes.conf

Windows

For simplicity configuration is done via appcmd.exe.

appcmd.exe set config -section:system.webServer/rewrite/globalRules /+"[name='Shibboleth',stopProcessing='True']" /commit:apphost
appcmd.exe set config -section:system.webServer/rewrite/globalRules /[name='Shibboleth'].match.url:"^(Shibboleth\.sso|shibboleth-sp).*" /commit:apphost

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

This will create a global rule to exclude Shibboleth authentication requests being sent to the Tomcat.
However, as this rule was created after the LearnProxy rule the rules will be processed in the wrong order.
To Reorder the rules.

  1. Open IIS Manager.
  2. Select the server name.
  3. Double-click URL Rewrite
  4. Select the rule called Shibboleth
  5. Select the Move Up Action until Shibboleth is above LearnProxy

Configure the Shibboleth connector to integrate with Blackboard Learn

Create a Shibboleth authentication provider

  1. Log into Blackboard Learn as an Administrator
  2. On the Administrator Panel, in the Building Blocks section, select Authentication.
  3. On the Authentication page, select Create Provider on the to access the action bar drop-down list and select Shibboleth.
    1. Provide a Name and Link Name.
    2. Set availability to Active.
    3. Set User Lookup Method to Username or Batch Uid

    The User Lookup Method will be determined by the Shibboleth Attribute that is mapped to the REMOTE_USER variable. The attribute must have a 1 to 1 relationship with the value returned from the User Lookup Method.

  4. Select Save and Configure.

    The Shibboleth Settings page appears, providing the information needed to configure the native SP later.

  5. Set Attribute Source as HTTP headers

    In Learn April 2014 Release and above both Apache and IIS use HTTP headers as the Attribute Source

  6. Make note of the Shibboleth Spoof Key
  7. Make note of the Secure Location URL
  8. Select Submit

Configure Shibboleth for Blackboard Learn

When exiting the shibboleth2.xml file, set the following attributes:

  • <ApplicationDefaults/> must set REMOTE_USER to the Shibboleth attribute that will be used to map to the Blackboard Learn Username or Batch Uid (User Lookup Method).

Additional configuration options for Windows

  • The <Site> element within <ISAPI> must set id to the numeric ID of the IIS site of the Blackboard Learn instance (Default Web Site).
  • <InProcess> must set spoofKey to the value shown on the Authentication Provider's Shibboleth Settings page.
  • The <safeHeaderNames> element within <ISAPI> must be set to "true" to remove all non-alphanumeric characters from the names of all SP-controlled headers.
  • A <Host> element within <RequestMap> is used to configure which content requires an authenticated Shibboleth session to access. This needs to be changed from the default of /secure to use the Secure Location URL provided in Create a Shibboleth Authentication Provider without the slash at the beginning.

Open shibboleth2.xml in a text editor such as vi or Notepad and add the following configuration elements:

UNIX example

<ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="uid">
<!-- config -->
</ApplicationDefaults>

Windows example

<InProcess logger="native.logger" spoofKey="47690fe2-f5b0-4d2c-916c-bfa562f065b7">
 <ISAPI normalizeRequest="true" safeHeaderNames="true">
 <Site id="1" name="server.pd.local"/>
 </ISAPI>
 </InProcess>
 <RequestMapper type="Native">
 <RequestMap>
 <Host name="sp.example.org">
 <Path name="webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin" authType="shibboleth" requireSession="true"/>
 </Host>
 </RequestMap>
 </RequestMapper>
 <ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="uid">
 <!-- config -->
 </ApplicationDefaults>

If the webserver is fronted by a load balancer and SSL is OffLoaded to the load balancer.

LB(https)->Apache(http)->Learn(http)

An additional configuration will be required in Shibboleth2.xml.

Set the <Sessions element handlerSSL="false" This will prevent Shibboleth trying to send SAML requests to the non secure port.

UNIX: Configure mod_shib for Blackboard Learn

By default, mod_shib is configured to protect the URL /secure. This needs to use the Secure Location URL provided in "Create a Shibboleth Authentication Provider"

As root:

cp /etc/httpd/conf.d/shib.conf /etc/httpd/conf.d/x-shib.conf

Open x-shib.conf in a text editor such as vi:
locate the section starting <Location /secure and update it.

<Location /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin>
  AuthType shibboleth
  ShibCompatWith24 On
  ShibUseHeaders On
  ShibRequestSetting requireSession 1
  require valid-user
  RewriteEngine On
  RewriteCond %{LA-U:REMOTE_USER} (.*)
  RewriteRule . - [E=RU:%1]
  RequestHeader set remote-user "%{RU}e" env=RU
  RequestHeader set Shib-Spoof-Check "3817e421-5a9f-4e9d-a51d-346ce688efab"
</Location>


This ensures that mod_shib ignores all requests except ones sent to /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin.

The value of Shib-Spoof-Check should match the value in the Learn UI this ensures the username passed on has not been configured outside of Learn.

Restart Shibboleth

Before Continuing as there have been configuration changes its best practice to restart the Webserver and Shibboleth services.

UNIX

This task needs superuser privileges.

/sbin/service shibd restart

sudo apachectl restart

Windows

  1. Select Start > Administrative Tools > Internet Information Services (IIS) Manager.
  2. In the right pane, under Actions, select Restart.
  3. Select Start > Administrative Tools > Services
  4. Locate Shibboleth 2 Daemon, right-click and select Restart

Test connection settings

  1. On the Administrator Panel, in the Building Blocks section, select Authentication.
  2. Open the menu for the service provider created earlier and select Test Connection Settings.

This triggers a Shibboleth login request. Confirm that the required attributes were passed back to Blackboard Learn.

Enable logout support within Blackboard Learn

Blackboard Learn can handle both front-channel and back-channel logout requests as described in the Shibboleth documentation. When using an Identity Provider (IdP) that supports Single Logout, This can feature can be activated. To configure Notifications Within Service Provider.

Add a <Notify> element to the shibboleth2.xml file, making use of the path provided, along with the public URL for the Blackboard Learn server, such as https://learnserver.example.edu.

<Notify Channel="back" Location="https://learnserver.example.edu/webapps/bb-auth-provider-shibboleth-BBLEARN/shibbolethLogout" />