Skip to main content
pdf?stylesheet=default
Blackboard Help

Integrating Shibboleth

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/Solaris 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 you configure the Shibboleth server, you first must create Blackboard Learn users using the same user ID that will be passed back to Blackboard Learn using the REMOTE_USER environment variable.

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 Installing Shibboleth

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

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

Basic Setup: Linux/Solaris

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

Step 1: Switch to Apache 2.x

Another key component of a Shibboleth Authentication Integration is the installation of Apache 2. Blackboard Learn currently ships with Apache 1.3, which is not compatible with Shibboleth 2.x. Blackboard Learn provides configuration settings that allow you to disable the internal Apache 1.3 distribution and use your own Apache 2.x installation. To learn more about switching to Apache 2.x and installing OpenSSL, see Installing and Configuring Apache 2.

After performing these steps, a Shibboleth-specific Apache change is required. The default Learn configuration uses ProxyPass to tunnel all URLs through to Tomcat. You must exclude the Shibboleth URLs so that they are handled internally by mod_shib:

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

Step 2: Create a Shibboleth Authentication Provider

  1. On the Administrator Panel, in the Building Blocks section, click Authentication.
  2. On the Authentication page, click 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. Click Save and Configure.

The Shibboleth Settings page appears, providing the information needed to configure the native SP later. Make note of the Secure Location URL shown here. The examples in this section use /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin.

Step 3: Install Native Shibboleth Provider

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

Step 4: Configure Your SP for Learn

When creating your shibboleth2.xml file, set the following attributes:

  • <ApplicationDefaults/> must set REMOTE_USER to the Shibboleth attribute that you intend to map to the Blackboard Learn username (or batch UID).
  • <ApplicationDefaults/> must set attributePrefix="AJP_" to allow Blackboard Learn to access to the Shibboleth Session ID value.

Example

<ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="eppn persistent-id targeted-id" attributePrefix="AJP_"> <!-- config --> </ApplicationDefaults>

Step 5: Configure mod_shib for Learn

By default, mod_shib is configured to protect the URL /secure. You must change this to use the Secure Location URL provided in "Step 2: Create a Shibboleth Authentication Provider," and use it when the Blackboard Learn Shibboleth Authentication is configured.

As root:

cp /etc/httpd/conf.d/shib.conf /etc/httpd/conf.d/shib.conf.orig

Edit shib.conf:

<Location /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin>
AuthType shibboleth
ShibRequestSetting requireSession 1
require valid-user

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

Basic Setup: Windows

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

Step 1: Create a Shibboleth Authentication Provider

  1. On the Administrator Panel, in the Building Blocks section, click Authentication.
  2. On the Authentication page, click Create Provider on the action bar to access the drop-down list and select Shibboleth.
    1. Provide a Name and Link Name.
    2. Set availability to Active.
  3. Click Save and Configure.

The Shibboleth Settings page appears, providing the information needed to configure the native SP later. Make note of the Secure Location URL shown here. The examples in this section use /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin.

Step 2: Install Native Shibboleth Provider

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

Step 3: Configure Your SP for Learn

When creating your shibboleth2.xml file, set the following attributes:

  • <ApplicationDefaults/> must set REMOTE_USER to the Shibboleth attribute that you intend to map to the Blackboard Learn username (or batch UID).
  • <ApplicationDefaults/> must set attributePrefix="AJP_" to allow Blackboard Learn to access to the Shibboleth Session ID value.
  • <InProcess> must set spoofKey to the value shown on the Authentication Provider's Shibboleth Settings page.
  • The <Site> element within <ISAPI> must set id to the numeric ID of the IIS site of your Blackboard Learn instance.
  • 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. You must change this from the default of /secure to use the Secure Location URL provided in "Step 1: Create a Shibboleth Authentication Provider," without the slash at the beginning.

Example

<InProcess logger="native.logger" spoofKey="47690fe2-f5b0-4d2c-916c-bfa562f065b7">
<ISAPI normalizeRequest="true" safeHeaderNames="true">
<Site id="1" name="sp.example.org"/>
</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="eppn persistent-id targeted-id" attributePrefix="AJP_">
<!-- config -->
</ApplicationDefaults>

<Notify Channel="back" Location="https://learnserver.example.edu/weba...ibbolethLogout" />

Test Connection Settings for All Shibboleth Installs

  1. On the Administrator Panel, in the Building Blocks section, click Authentication.
  2. Access the contextual menu for the SP that you created and select Test Connection Settings.

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

Enable Logout Support Within Blackboard Learn for All Shibboleth Installs

Blackboard Learn can handle both front-channel and back-channel logout requests as described in the Shibboleth documentation. If you are using an Identity Provider (IdP) that supports Single Logout, you can activate this feature within Blackboard Learn.

Configure Notifications Within Service Provider for All Shibboleth Installs

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

<Notify Channel="back" Location="https://learnserver.example.edu/weba...ibbolethLogout" />